Skip to main content

Changelog

Updates, changes, and improvements at Retool.

Refer to the stable and edge release notes for detailed information about self-hosted releases.

Self-hosted Retool 4.0 upgrade FAQ

If you have an existing Retool deployment instance, this FAQ can provide guidance as you prepare an upgrade plan.

I'm on Amazon ECS. Can I upgrade in place?​

No. Retool 4.0 introduces the agent sandbox service, which requires a custom Linux seccomp profile. Amazon ECS Fargate does not support custom seccomp profiles, and ECS EC2 does not meet the other requirements for a supported production deployment.

There is no in-place upgrade path from ECS to Retool 4.0. You must migrate to a Kubernetes deployment before upgrading. Retool's Terraform blueprints are the officially supported path for new Kubernetes deployments.

Contact your Retool account team to plan the migration. For step-by-step instructions, refer to Migrate from ECS to Kubernetes.

I'm running Kubernetes with raw manifests. Can I upgrade in place?​

No. Raw Kubernetes manifests are not a supported deployment configuration, and services introduced in Retool 4.0 are shipped and configured through the Retool Helm chart. There is no in-place upgrade path for raw manifest deployments.

You must migrate to a Helm-based deployment before upgrading to Retool 4.0. Retool's Terraform blueprints are the recommended path. If you have an existing Helm deployment, the Helm upgrade guide covers how to add the new services.

Contact your Retool account team if you need migration assistance.

I'm running Docker Compose in production. What should I do?​

Retool does not support Docker Compose for production deployments. The agent sandbox service requires resource isolation and pod-level scheduling that a single-VM stack cannot reliably provide.

If you are using Docker Compose in production, migrate to Kubernetes before upgrading. Refer to Migrate from Docker Compose to Kubernetes for step-by-step instructions.

If you are using Docker Compose for non-production or development purposes, you can upgrade in place. Refer to Upgrade your Docker Compose deployment.

Can I upgrade to Retool 4.0 without enabling the new services?​

Yes. All new services introduced in Retool 4.0 (the agent sandbox, JS executor, MCP server, r2 agent, and git server) are disabled by default in Helm chart version 6.11.0. Upgrading the chart without enabling them is safe and fully backward compatible.

You can enable individual services at any time after upgrading. Refer to the Helm upgrade guide for instructions on enabling each service.

What seccomp profiles does the agent sandbox require? Is this more or less secure than privileged mode?​

The agent sandbox uses gVisor for container sandboxing and requires a custom seccomp profile on each cluster node — there is no privileged mode equivalent. The profile grants only the specific syscalls gVisor needs and does not require CAP_SYS_ADMIN.

This is significantly more secure than privileged mode. Customers who previously ran code-executor without privileged mode can apply the same approach for the agent sandbox.

For the full seccomp profile breakdown and a comparison with code-executor, see Custom code execution security.

My ENCRYPTION_KEY contains non-ASCII characters. Do I need to change it before upgrading?​

Yes. From version 3.332.4, ENCRYPTION_KEY must contain only ASCII characters. If your key contains non-ASCII characters, upgrading without rotating it first will cause decryption failures — look for ERR_OSSL_BAD_DECRYPT in your logs.

Rotate your encryption key before upgrading. Contact your Retool account team if you need assistance with the rotation process.

I use SAML SSO. Are there any new requirements?​

Yes, if your users sign in via SP-initiated SAML (starting the login flow from Retool rather than your IdP dashboard). Retool now binds each login to the AuthnRequest that started it using a short-lived, HTTPS-only cookie. Two requirements apply:

  • Retool must be served over HTTPS. Do not enable COOKIE_INSECURE. The cookie is set SameSite=None; Secure, which browsers only return over HTTPS. SP-initiated logins will fail on plain HTTP.
  • Use a single consistent hostname. The Assertion Consumer Service (ACS) URL registered in your IdP must match the hostname your users start login from. Standard single-hostname deployments need no change.

Standard IdPs (Okta, Entra ID, OneLogin, ADFS, Ping, Google Workspace) return the required InResponseTo value automatically.

IdP-initiated logins — launching Retool directly from your IdP dashboard — are unaffected. Users must complete a login within 10 minutes of starting it.

To disable this validation: set DISABLE_SAML_INRESPONSETO_VALIDATION=true and restart.

I use Temporal-in-Helm. What do I need to do?​

Temporal-in-Helm has been removed in Retool 4.0. Retool no longer ships a Temporal cluster as part of the Helm chart. You must migrate to an external Temporal provider before or during your upgrade.

Retool supports two options:

  • Temporal Cloud (recommended): a fully managed Temporal service. Requires outbound network access to Temporal Cloud egress endpoints on ports 443 and 7233.
  • Self-hosted Temporal: an externally managed Temporal cluster you operate. Retool does not provide support for the Temporal cluster itself.

After upgrading to Retool 4.0, an admin user must complete Temporal setup from within Retool: click the Workflows nav item and follow the in-product setup steps. A valid license key is required.

If you have Temporal-in-Helm data (workflow history) you want to preserve, contact your Retool account team before upgrading.