Self-hosted Retool 4.0 Stable
Retool 4.0 is the most significant infrastructure change to self-hosted Retool since launch. It introduces the new app builder built on React, with AI-assisted building and a real-time collaborative editing environment. These features are powered by a set of additional services: the agent sandbox, JS executor, MCP server, and r2 agent. These services run alongside other Retool containers and require Kubernetes with Helm chart 6.11.0 or later.
For new deployments: Retool now provides Terraform blueprints that automatically provision all required AWS infrastructure (VPC, EKS cluster, RDS, S3, load balancer, ACM certificate) and deploy Retool via Helm. This is the recommended path for production.
For existing deployments: The upgrade path depends on how you're currently deployed. New services are disabled by default so you can upgrade the chart first and enable them when ready. Some deployment configurations require migration before upgrading.
In addition, a database migration is performed to prepare for upcoming improvements to organization permissions. This migration does not affect any functionality within this release but any migration issues must be resolved before attempting to upgrade to a future release.
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 setSameSite=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.
Permissions database migration in self-hosted Retool 4.0
Self-hosted Retool 4.0 includes an automatic database migration that prepares your instance for upcoming improvements to how Retool handles organization permissions. This migration runs in the background during deployment and does not affect any functionality.
Retool strongly recommends upgrading to self-hosted Retool 4.0 before upgrading to a future release. Doing so allows the migration to run as intended, giving you time to identify and resolve any issues before they become critical. If you attempt to upgrade a pre-4.0 release to a post-4.0 release, this may result in migration issues which can impact the deployment until resolved.
What happens when you upgrade
When you deploy Retool 4.0 stable, the migration runs automatically in the background. In most cases, no action is required.
If the migration fails—even for a single space within your instance—all organization admins will see a notification banner across all settings pages to indicate that the database is in an inconsistent state. This notification includes a link for an admin to trigger the migration again.
The database integrity check can take approximately three hours from upgrade completion. If the check fails, the notification banner is displayed. For larger instances, this check can take up to 15 hours.
If the migration fails
Should the migration fail, no existing functionality is impacted. In most cases, an admin can trigger the migration again. The option to trigger a migration again is disabled if it is already in progress so it cannot be triggered multiple times.
If re-running does not resolve the issue, contact our support team as soon as possible.
Any migration failures must be resolved before upgrading to a future stable release. Attempts to upgrade to a future release with a failed migration will fail and would require rolling back until the migration failure is resolved.