Skip to main content

Upgrade your Helm deployment

Upgrade an existing self-hosted Retool Helm deployment to the latest version.

This guide covers upgrading an existing self-hosted Retool Helm + Kubernetes deployment to Retool 4.0 and enabling R² features. R² components are disabled by default in chart version 6.11.0 and must be explicitly enabled via the rr.* namespace in your Helm values. Upgrading the chart without enabling them is safe and fully backward compatible.

Retool's officially supported deployment configuration for Kubernetes is the Terraform blueprints. This guide is provided for customers upgrading existing Helm deployments and is offered for convenience, but Retool recommends migrating to the Terraform blueprints deployment for full support going forward.

Reference configuration for all steps is available in the retool-helm repository and Terraform blueprints.

What changed from Retool 3.x​

Retool 4.0 introduces breaking changes to the Helm chart that affect existing values files:

ChangeDetails
Helm values restructured under rr.*All R² components (jsExecutor, agentSandbox, rrGitServer) move under a single rr: key with rr.enabled: true as the master switch. The old top-level keys cause the chart to fail loudly — this is intentionally not backwards compatible.
Blob storage is now requiredObject storage (S3, Azure Blob, or GCS) is a platform requirement for app storage, Git repository storage, and sandbox snapshots. It was optional in Retool 3.x.
Same-origin networking is the defaultThe agent sandbox uses your existing Retool domain and ingress. No wildcard subdomain (agent-proxy.*), wildcard TLS certificate, or separate ingress route is required.
Secrets simplifiedOnly the JWT keypair is required for the agent sandbox. Postgres is inherited from the backend automatically — no separate schema config needed.
mcp stays top-levelThe MCP service uses mcp.enabled: true, not rr.mcp. It requires separate OAuth configuration and is not part of the rr.enabled master switch.

Before you upgrade​

Use this checklist as you prepare the upgrade to ensure you have everything ready.

After upgrading, a database migration runs automatically in the background. Monitor your instance for a banner in Settings pages — if it appears, an admin can trigger the migration again from there. See Permissions database migration for details.

Update the Helm chart repository​

Update your local chart cache to make chart version 6.11.0 available:

helm repo add retool https://charts.retool.com
helm repo update

Verify the chart is available:

helm search repo retool/retool --versions | grep 6.11.0

Terraform​

Set the repository and version in your helm_release resource:

resource "helm_release" "retool" {
  repository = "https://charts.retool.com"
  chart      = "retool"
  version    = "6.11.0"
  # ...
}

Add core values​

Add the following to your values.yaml. Use image tag 4.0.0-stable. Replace yourdomain.com with your existing Retool base domain (the current value of BASE_DOMAIN):

Enabling the agent sandbox requires a custom Linux seccomp profile on each cluster node. gVisor uses it for sandboxing. Without it, agent sandbox pods will fail to start. The profile is published in the Helm chart at charts/retool/files/gvisor-seccomp.json. Amazon EKS supports custom seccomp profiles by default. If your cluster has a restrictive security policy, verify this before enabling.

image:
  tag: X.Y.Z-stable  # use the tag shown above

rr:
  enabled: true   # master switch: enables agent, js-executor, agent-sandbox, and git-server

  agentSandbox:
    externalSecret:
      name: 'agent-sandbox-env'
    proxy:
      backendDomainSuffixes: "yourdomain.com"  # replace with your Retool base domain

  gitServer:
    enabled: true

mcp:
  enabled: true   # optional; requires separate OAuth config; NOT included in rr.enabled

Replace X.Y.Z-stable with the current stable version from the release notes. The minimum supported version for Retool 4.0 is 4.0.0-stable.

To disable a single component while keeping the master switch on, override it explicitly:

rr:
  enabled: true
  jsExecutor:
    enabled: false   # overrides master switch for this component only

The agent sandbox inherits the backend Postgres connection automatically on a separate internal schema. No postgres: config is needed unless your backend database password is injected via envFrom or an external secret.

Create agent sandbox secrets​

Only the JWT keypair is required. Generate it with the following commands:

# Generate a new private key
openssl genpkey -algorithm EC -pkeyopt ec_paramgen_curve:P-256 -out private_key.pem

# Derive the public key
openssl pkey -in private_key.pem -pubout -out public_key.pem

Create a Kubernetes Secret with the keypair:

cat > agent-sandbox-env.yaml << EOF
apiVersion: v1
kind: Secret
metadata:
  name: agent-sandbox-env
  namespace: default  # use the namespace where Retool is deployed
type: Opaque
data:
  jwt-public-key: $(cat public_key.pem | base64 -w0)
  jwt-private-key: $(cat private_key.pem | base64 -w0)
  # Optional additional keys:
  # encryption-key: ...
  # api-secret: ...
  # postgres-url: ...  (only if your backend DB password is injected via envFrom)
EOF

kubectl apply -f agent-sandbox-env.yaml

The externalSecret.name reference in your values.yaml (already included in the core values block above) tells the agent sandbox where to find this secret.

For Terraform users, refer to secrets.tf for creating these secrets within Terraform and mapping them into Kubernetes via External Secrets Operator.

Configure blob storage​

Each deployment requires an object storage bucket with read/write credentials. Use the rr.blobStorage: block in values.yaml. The chart renders the required environment variables automatically.

rr:
  blobStorage:
    s3:
      bucket: <your-bucket>
      region: <your-region>
      accessKeyId: <key-id>
      secretAccessKey: <secret>  # or use secretAccessKeySecretName / secretAccessKeySecretKey
      endpoint: ""               # optional; for S3-compatible stores

IAM roles are supported as an alternative to access keys. For Terraform users, refer to the S3 and IAM reference configuration.

If you inject blob storage credentials via envFrom (e.g., a ConfigMap or Secret splat) instead of the rr.blobStorage: block, set rr.gitServer.skipBlobStorageValidation: true to bypass the chart's validation check.

Configure networking​

The agent sandbox uses same-origin networking by default — it routes through your existing Retool ingress with no additional configuration. Your existing ingress block is unchanged:

ingress:
  enabled: true
  ingressClassName: ''  # your existing value
  hosts:
    - host: yourdomain.com
      paths:
        - path: '/'
          pathType: Prefix

No wildcard TLS certificate, wildcard DNS, or separate ingress route is required. The MCP service (https://yourdomain.com/mcp/*) is also routed through the existing ingress automatically.

Optional: dedicated proxy subdomain​

If you need the agent sandbox proxy on a separate subdomain (for example, to satisfy network segmentation requirements), set rr.agentSandbox.frontendWsProxyDomain and enable the proxy ingress:

rr:
  agentSandbox:
    frontendWsProxyDomain: "https://agent-proxy.yourdomain.com"
    proxy:
      ingress:
        enabled: true
        ingressClassName: ''
        host: agent-proxy.yourdomain.com

Using a separate proxy subdomain requires a wildcard TLS certificate covering *.yourdomain.com.

Cloud-specific notes​

Details
AWS: Karpenter

Karpenter is incompatible with the current agent sandbox architecture. The agent-sandbox-job pods use an extended resource (smarter-devices/net_tun) that causes Karpenter to fail to schedule them.

To fix this: run a recent version of Karpenter with the nodeOverlay feature gate enabled, and create a NodeOverlay custom resource. Refer to this reference configuration.

Apply the changes​

Run the Helm upgrade:

helm upgrade retool retool/retool \
  --version 6.11.0 \
  -f values.yaml

Complete setup in the Retool UI​

Once the deployment is healthy, an admin user should complete the following:

R2 features require feature flags enabled at the license key level by Retool staff. Contact your Retool account team to have them enabled after your deployment is up.

  1. Set up Retool AI: go to Resources → Create new → Resource and create an OpenAI or Anthropic resource using your own API keys. Then go to Settings → AI to enable Assist and select your preferred resource under Apps (beta).
  2. Enable Temporal: click the Workflows nav item and follow the in-product setup steps to enable Temporal Cloud. A valid license key is required.

Retool-managed AI keys are not compatible with self-hosted deployments. The managed key proxy has a 29-second timeout; many agent operations exceed this and will fail silently. Configure your own API keys (Bring Your Own Key) under Resources → AI.