Skip to main content
This page is unlisted and can only be accessed directly via URL. It is excluded from the site navigation and search results.

Deploy Retool on Kubernetes with Helm

Deploy Retool on Kubernetes with the Helm package manager using your own cluster.

This guide is for customers deploying on an existing Kubernetes cluster. For new production deployments, use Terraform blueprints, which provision all required infrastructure and deploy Retool via Helm automatically.

RequirementDetails
Retool license keyObtain from the Retool self-hosted Portal or your account manager.
Kubernetes clusterAmazon EKS.
HelmHelm 3.3.1 or later.
kubectl CLIA working kubectl installation connected to your cluster.
PostgreSQL databaseAn externally managed database. Enable the uuid-ossp module and use the Read Committed isolation level. See the architecture guide for Retool's table requirements.
Object storageS3, Azure Blob, or GCS. Used for app storage, Git repositories, and sandbox snapshots. See Configure blob storage.
Wildcard DNSConfigure a wildcard DNS record (e.g., *.yourdomain.com) pointing to your load balancer. This is required for the agent sandbox proxy subdomain.
Wildcard TLS certificateA certificate covering both your primary domain and all subdomains (e.g., yourdomain.com and *.yourdomain.com). A single-hostname certificate will not cover agent-proxy.yourdomain.com and will cause TLS failures. See Configure TLS.
TemporalRequired for Workflows and agent sandbox orchestration. Retool-managed Temporal Cloud is recommended.
Custom seccomp profileThe agent sandbox uses gVisor for sandboxing and requires a custom seccomp profile on each node. Amazon EKS supports this by default. Verify your cluster permits custom seccomp profiles before deploying — locked-down enterprise clusters and Amazon ECS do not support this.

Temporal​

Temporal is a distributed system used to schedule and run asynchronous tasks for Retool Workflows and Retool Agents. A self-hosted Retool instance uses a Temporal cluster to facilitate the execution of each workflow amongst a pool of self-hosted workers that make queries and execute code in your VPC. Temporal manages the queueing, scheduling, and orchestration of workflows to guarantee that each workflow block executes in the correct order of the control flow. It does not store any block results by default.

You can use a Retool-managed cluster on Temporal Cloud, which is recommended for most use cases. You can also use an existing self-managed cluster that is hosted on Temporal Cloud or in your own infrastructure. Alternatively, you can spin up a new self-hosted cluster alongside your self-hosted Retool instance.

Recommended

You should use a Retool-managed cluster if:

  • You don't have an existing cluster which you prefer to use.
  • Your cluster only needs to be used for a self-hosted Retool deployment.
  • You don't want to manage the cluster directly.
  • You have a single or multi-instance Retool deployment, where each instance requires its own namespace.

Retool admins can enable Retool-managed Temporal. To get started, navigate to the Retool Workflows page and click Enroll now. Once you update your configuration, return to the page and click Complete setup.

It can take a few minutes to initialize a namespace in Retool-managed Temporal.

Retool-managed Temporal Clusters are hosted on Temporal Cloud. Your self-hosted Retool deployment communicates with the cluster when building, deploying, and executing Retool Workflows. All orchestration data to Temporal is fully encrypted and uses the private encryption key set for your deployment.

Cluster size​

The following services add to the cluster's resource requirements. The agent sandbox job pods scale with active builder sessions:

ComponentCPUMemory
js-executor6 cores6 GiB
r2-worker1 core2 GiB
agent-sandbox-proxy¼ core256 MiB
agent-sandbox-controller¼ core256 MiB
agent-sandbox-job pods (×5 default)5 cores10 GiB

Plan for workload nodes with at least 32 cores and 64 GiB memory available across the pool. The agent sandbox job pods auto-scale with builder sessions, so ensure your node autoscaler can accommodate peak usage.

Use the following command to retrieve the capacity of your nodes.

$ kubectl describe nodes

In the Capacity section, verify the cpu and memory values meet the above requirements.

Capacity:
  attachable-volumes-aws-ebs:            25
  cpu:                                   8
  ephemeral-storage:                     83873772Ki
  hugepages-1Gi:                         0
  hugepages-2Mi:                         0
  memory:                                7931556Ki
  pods:                                  29

Cluster storage class​

If you want to mount volumes, ensure the volume supplied by your cloud provider can be mounted to multiple nodes. To identify your cluster's storage class, run the command

$ kubectl get storageclass

Reference your cloud provider's documentation to verify that this storage class supports the ReadWriteMany access mode.

Network requirements​

Self-hosted Retool deployments must allow access to Retool's IP addresses or domains. If you make use of outbound firewall rules, include the following IP addresses or domains in its allowlist. These allow your deployment to connect to Retool's license check, user authentication, and usage reporting services.

CIDR IP addresses
35.92.202.168/29
44.211.178.248/29
Individual IP addresses
35.92.202.168
35.92.202.169
35.92.202.170
35.92.202.171
35.92.202.172
35.92.202.173
35.92.202.174
35.92.202.175
44.211.178.248
44.211.178.249
44.211.178.250
44.211.178.251
44.211.178.252
44.211.178.253
44.211.178.254
44.211.178.255
Domains
licensing.tryretool.com
invites.tryretool.com
email-service.retool.com
p.tryretool.com
specs.tryretool.com
pypi.org

Egress is required when using Retool-managed Temporal. Refer to the Egress section of the Temporal conceptual guide for more information.

HTTP proxy connections​

Retool supports connections to the internet through a HTTP proxy. Add HTTP_PROXY=http://example.com:8080 to your deployment's docker.env file with the required URL and port number.

Source control proxy configuration​

If your environment routes outbound traffic through a proxy, source control connections (such as GitHub or GitLab) require additional configuration. The standard HTTP_PROXY and HTTPS_PROXY variables are not sufficient for source control operations.

Set the following GLOBAL_AGENT_* variables in your deployment, using the same values as your HTTP_PROXY, HTTPS_PROXY, and NO_PROXY settings:

GLOBAL_AGENT_HTTPS_PROXY=https://your-proxy:8080
GLOBAL_AGENT_HTTP_PROXY=http://your-proxy:8080
GLOBAL_AGENT_NO_PROXY=localhost,127.0.0.1,.internal.example.com

Then enable the proxy agent for the services that need outbound access:

GLOBAL_AGENT_BACKEND=true
GLOBAL_AGENT_JOBS_RUNNER=true
GLOBAL_AGENT_DB_CONNECTOR=true

License checks​

Retool uses HTTP to connect to licensing.tryretool.com on port 443 to verify your license. License checks are made at least once a day.

Inviting users​

Retool connects to invites.tryretool.com and email-service.retool.com on port 443 when inviting users. Retool verifies the users are authorized under your current billing plan, and then sends an invite to their email address.

Usage reporting​

Retool sends application usage information to p.tryretool.com on port 443, which is used to inform product decisions.

Usage categories​

The categories of usage information sent to Retool includes, but is not limited to, the following:

  • Page views, along with the page URL.
  • Query saves, including the query name and type.
  • Component creation and the component type.
  • Query preview, including the query name and type.
  • Adding a resource, including the resource name and type.

Events are also sent with the hostname, public IP address, browser user-agent string, and the user's email address.

1. Add the Retool Helm chart repository​

Use the following command to add the Retool Helm repository.

Add Retool chart
$ helm repo add retool https://charts.retool.com

Run helm search repo retool/retool to confirm you can access the Retool chart.

Verify Retool chart
NAME            	CHART VERSION	APP VERSION	DESCRIPTION
retool/retool   	6.11.0       	           	A Helm chart for Kubernetes

2. Download Helm configuration file​

Retool's Helm chart is configured using a values.yaml file. Download a copy of values.yaml to your local machine, using the command below. Open values.yaml in a text editor or IDE.

curl -L -o values.yaml https://raw.githubusercontent.com/tryretool/retool-helm/main/values.yaml

3. Update Helm configuration​

In Kubernetes, you can store configuration options in plain text or use Kubernetes secrets. The following example sets config.licenseKey as plain text.

config:
  licenseKey: "XXX-XXX-XXX"

A Kubernetes secret is an object that contains multiple key-value pairs. You need both the secret name and the key to configure the values.yaml file. The example below uses a value stored in the license-key-secret under the key license-key.

config:
  licenseKeySecretName: license-key-secret
  licenseKeySecretKey:  license-key

Retool recommends storing sensitive data—for example, passwords and credentials—as Kubernetes secrets, especially if you commit values.yaml to source control.

Set the following values in values.yaml.

To generate 36-character random strings for config.encryptionKey and config.jwtSecret, run the command openssl rand -base64 36.

SettingDescription
config.licenseKeyLicense key, in plain text or as a secret value.
config.encryptionKeyKey used to encrypt the database. Generate a random string with openssl.
config.jwtSecretSecret used to sign authentication requests from Retool's server. Generate a random string with openssl.
image.tagVersion of Retool to install, in the format X.Y.Z. self-hosted Retool with Workflows requires 2.108.4 or later when using a local Temporal Cluster, or 3.6.14 or later for Retool-managed Temporal.
config.useInsecureCookiesWhether to allow insecure cookies. Set to true if you have not configured SSL. Set to false if you use HTTPS to connect to the instance.
workflows.enabledWhether to enable Retool Workflows. Set to true. Defaults to true for Retool version 3.6.14 or later.
codeExecutor.enabledWhether to enable the Code Executor service. Set to true. Defaults to true for Retool version 3.20.15 or later, and automatically sets the image tag for tryretool/code-executor-service corresponding to tryretool/backend.
postgresql.enabledWhether to use the PostgreSQL subchart to create a containerized instance of PostgreSQL. Thie default is true. This is not suitable for production use cases, and the Retool Storage database should be hosted on an external, managed database. Set this to false.
config.postgresqlDetails of the external PostgreSQL database for the deployment instance to use.

Each workflow worker can process approximately 10 queries per second (QPS). Increase the workflow replicaCount if this is not high enough for your needs. You should be able to scale this to approximately 40 QPS, using four workflow workers, before you need to make infrastructure changes.

Enable services​

Add the following to values.yaml to enable the services. Replace yourdomain.com with your Retool base domain. Use image tag 4.0.0-stable — all services must run the same tag.

image:
  tag: X.Y.Z-stable  # use the tag shown above — all services must match

rrGitServer:
  enabled: true

r2Agent:
  enabled: true

jsExecutor:
  enabled: true

agentSandbox:
  enabled: true
  postgres:
    schema: 'agent_executor'
  frontendWsProxyDomain: "https://agent-proxy.yourdomain.com"
  proxy:
    backendDomainSuffixes: "yourdomain.com"

mcp:
  enabled: true

Configure agent sandbox secrets​

The agent sandbox requires a set of secrets and a Postgres connection URL. It uses the same Postgres instance as Retool but a separate schema (agent_executor).

Postgres connection string format​

postgresql://${username}:${urlencode(password)}@${db_address}:${db_port}/${db_name}

Generate secrets​

openssl genpkey -algorithm EC -pkeyopt ec_paramgen_curve:P-256 -out private_key.pem
openssl pkey -in private_key.pem -pubout -out public_key.pem
head -c 64 /dev/urandom | base64 -w0 > agent_encryption_key.txt
head -c 64 /dev/urandom | base64 -w0 > agent_api_secret.txt

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)
  encryption-key: $(cat agent_encryption_key.txt | base64 -w0)
  api-secret: $(cat agent_api_secret.txt | base64 -w0)
  postgres-url: $(echo "postgresql://..." | base64 -w0)
EOF

kubectl apply -f agent-sandbox-env.yaml

Reference the secret in values.yaml:

agentSandbox:
  externalSecret:
    name: 'agent-sandbox-env'

Set encryption key​

Self-hosted Retool deployments use an encryption key to encrypt:

  • Private keys in the PostgreSQL database of the self-hosted Retool instance.
  • All data stored in Temporal when deploying self-hosted Retool.

Set the ENCRYPTION_KEY environment variable for your deployment.

Configure Temporal​

Recommended

Allow your deployment to connect to Temporal​

Open up egress to the public internet on ports 443 and 7233 to allow outbound-only connections to Temporal Cloud from your deployment. This is so services can enqueue work to, and poll work out, of Temporal.

Temporal Cloud does not have a static IP range to allow list. If more specificity is required, egress is required on ports on the following domains:

PortDomains
443*.retool.com, *.tryretool.com, *.temporal.io
7233*.tmprl.cloud

Kubernetes pods are non-isolated for egress by default thereby allowing all outbound connections. If the Retool backend or workers cannot connect to Temporal Cloud, check your egress NetworkPolicy for any issues.

Configure Helm for Temporal Cluster​

Update the values.yaml configuration file to specify whether to use a Retool-managed cluster or a self-managed one.

VariableDescription
.Values.workflows.enabledWhether to enable workers and workflow backend pods. Set to true.
.Values.codeExecutor.enabledWhether to enable code executor pods. Set to true.
.Values.workflows.temporal.enabledWhether to use a self-managed Temporal Cluster. Set to false.

The retool-temporal-services-helm subchart (local Temporal bundled into the Helm chart) has been removed. If your deployment previously used this subchart, migrate to a Retool-managed cluster or configure a self-managed Temporal cluster before upgrading to chart version 6.11.0. Refer to Temporal for more information.

4. Configure blob storage​

Retool requires object storage for app storage, Git repository storage, and agent sandbox snapshots. Use the blobStorage: block in values.yaml — the chart renders the required environment variables automatically.

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 blobStorage: block, set rrGitServer.skipBlobStorageValidation: true to bypass the chart's validation check.

5. Configure networking​

Two routes are required in addition to the main Retool ingress:

  • https://agent-proxy.yourdomain.com → agent-sandbox-proxy service
  • https://yourdomain.com/mcp/* → mcp service

Configure TLS​

The agent sandbox proxy runs on the subdomain agent-proxy.yourdomain.com and requires a wildcard TLS certificate (e.g., valid for yourdomain.com and *.yourdomain.com). A single-hostname certificate will not cover this subdomain and will cause silent TLS failures.

Recommended options:

  • Let's Encrypt with DNS-01 challenge — automatic renewal, no public ingress required for certificate verification
  • BYO wildcard certificate — manual renewal

For Let's Encrypt wildcard certificates using cert-manager with DNS-01 challenge, refer to Configure SSL and custom certificates.

Configure ingress​

ingress:
  enabled: true
  ingressClassName: ''  # replace as needed
  hosts:
    - host: yourdomain.com
      paths:
        - path: '/'
          pathType: Prefix

agentSandbox:
  proxy:
    ingress:
      enabled: true
      ingressClassName: ''  # same value as above
      host: agent-proxy.yourdomain.com

Cloud-specific notes​

Details
Amazon EKS — Karpenter

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

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.

6. Install self-hosted Retool​

After updating the configuration, install self-hosted Retool.

helm install my-retool retool/retool -f values.yaml

After installing Retool, run kubectl get pods to verify all services are running. A full deployment should include pods for the core services, workflow services, and agent sandbox components:

Verify pods
my-retool-api-xxx                              1/1     Running   0   5m
my-retool-jobs-runner-xxx                      1/1     Running   0   5m
my-retool-workflows-worker-xxx                 1/1     Running   0   5m
my-retool-workflows-backend-xxx                1/1     Running   0   5m
my-retool-code-executor-xxx                    1/1     Running   0   5m
my-retool-js-executor-xxx                      1/1     Running   0   5m
my-retool-agent-sandbox-controller-xxx         1/1     Running   0   5m
my-retool-agent-sandbox-proxy-xxx              1/1     Running   0   5m
my-retool-agent-sandbox-job-xxx (×5)           1/1     Running   0   5m

All services must run the same image tag. Version mismatches across services will cause unexpected failures, including silent hangs during app operations.

Once the main service is running, verify the installation by port forwarding to localhost.

kubectl port-forward my-retool-7898474bbd-69zjt 3000:3000

You can then access Retool at http://localhost:3000/.

Additional configuration​

The following configuration steps are optional but strongly recommended for using Retool in a production environment.

Whenever you run helm upgrade, use the --version flag to specify the chart's version number. Otherwise, Helm upgrades to the latest chart version, which may cause compatibility issues. You can check the release version of your deployment with the command helm list.

Add environment variables​

Environment variables provide ways to configure a Retool instance. The values.yaml file has three locations to add environment variables.

ObjectType
envPlain text key-value pairs.
environmentSecretsPlain text or Kubernetes secrets.
environmentVariablesPlain text or Kubernetes secrets.

Do not store sensitive information, such as access tokens, in env. Use environmentSecrets or environmentVariables as they can populate environment variables from Kubernetes secrets.

Mount volumes​

There are several use cases which require the use of volumes. For example, when configuring a gRPC resource, you need to mount a volume containing the protos files to the Retool deployment. Follow these instructions to create a persistent volume and copy files from your local machine to the volume.

1. Enable PersistentVolumeClaim​

The Helm chart defines a PersistentVolumeClaim (PVC) which is automatically mounted to the Retool pods, enabling Retool to access files within this volume. The PVC is disabled by default. To enable the persistentVolumeClaim, modify your values.yaml file:

persistentVolumeClaim:
  enabled: true
  existingClaim: ""

If you have an existing PVC in your Kubernetes cluster to use, you can specify its name in existingClaim. Otherwise, leave existingClaim blank.

2. Set security context​

In a later step, you use kubectl cp to copy files from your local machine to the Kubernetes cluster, which requires the pod to run with root privileges. Modify your deployment so the pods run as root by changing the securityContext in your values.yaml file:

securityContext:
  enabled: true
  runAsUser: 0

Use helm to perform the upgrade and include the Helm chart version number. Retool requires version 6.1.1 or later.

helm upgrade -f values.yaml my-retool retool/retool --version 6.1.1

3. Verify pods​

Run kubetcl get pods to verify pods are running.

my-retool-7898474bbd-pr8n6               1/1     Running   1 (8h ago)   8h
my-retool-jobs-runner-74796ddd99-dd856   1/1     Running   0            8h
my-retool-postgresql-0                   1/1     Running   0            8h

4. Copy files​

Next, copy the protos files from your local machine to the PVC. Note from kubectl get pods the three pods in the deployment: the main, jobs-runner, and postgresql containers. Identify the name of the main container.

Ensure you local machine has a folder named protos and run the following command, and replacing my-retool-7c4c89798-fqbh7 with the name of your Retool container.

kubectl cp protos/ my-retool-7c4c89798-fqbh7:/retool_backend/pv-data/protos

4. Set env​

If you're configuring gRPC, you need to specify the location of the protos directory. In values.yaml, set the PROTO_DIRECTORY_PATH environment variable.

env:
  PROTO_DIRECTORY_PATH: "/retool_backend/pv-data/protos"

5. Reset security context​

Revert the security context of your deployment back to a disabled state.

securityContext:
  enabled: false
  runAsUser: 1000

Use helm to perform the upgrade and include the Helm chart version number. Retool requires version 6.1.1 or later.

helm upgrade -f values.yaml my-retool retool/retool --version 6.1.1

Configure SSL​

When configuring SSL, you can use Let's Encrypt to provision a certificate, or provide your own. Refer to Configure SSL and custom certificates for more detail on certificates.

1. Install cert-manager​

First, add the jetstack Helm repository if you haven't already.

helm repo add jetstack https://charts.jetstack.io

Next, run the following command to install cert-manager.

helm install \
cert-manager jetstack/cert-manager \
--namespace cert-manager \
--create-namespace \
--version v1.11.0 \
--set installCRDs=true --set ingressShim.defaultIssuerName=letsencrypt-prod \
--set ingressShim.defaultIssuerKind=ClusterIssuer \
--set ingressShim.defaultIssuerGroup=cert-manager.io

2. Configure certificate issuer​

Create a file called production-issuer.yml. Copy the following configuration, replace the example email with your email, and paste it into the new file.

apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt-prod
spec:
  acme:
    server: https://acme-v02.api.letsencrypt.org/directory
    email: example@example.com
    privateKeySecretRef:
      name: letsencrypt-prod
    solvers:
      - http01:
          ingress:
            class: nginx

3. Create the certificate manager​

First, use kubectl to create the certificate manager as ClusterIssuer.

kubectl apply -f production-issuer.yml

4. Verify pod​

Run kubectl get clusterissuer to verify that the ClusterIssuer pod is ready.

NAME               READY   AGE
letsencrypt-prod   True    10m

5. Update ingress configuration​

Add the annotations section to your ingress and modify the host and hosts placeholders accordingly.

ingress:

  ...

  annotations:
    kubernetes.io/tls-acme: "true"
    certmanager.io/cluster-issuer: letsencrypt-prod
  hosts:
  - host: example.example.com
    paths:
      - path: /
  tls:
  - secretName: letsencrypt-prod
    hosts:
      - example.example.com

6. Apply changes​

After the pods restart, you can access the page in your browser using TLS.

Complete in-product setup​

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

  1. Enable Temporal — click the Workflows nav item and follow the in-product steps to configure Temporal Cloud. A valid license key is required.
  2. Set up Retool AI — go to Settings → AI to enable Assist, then go to Resources → AI to configure your AI provider keys.

Retool-managed AI keys are not compatible with self-hosted deployments. The managed key proxy has a 29-second timeout that agent operations regularly exceed, causing silent failures. Configure your own API keys (Bring Your Own Key) under Resources → AI.

Update your Kubernetes instance​

Follow these instructions to update your Retool instance to a newer release version.

Retool 4.0 requires Helm chart version 6.11.0 or later. If you are upgrading to Retool 4.0 from an earlier chart version, refer to the Helm upgrade guide for the full steps to enable the new services before running a standard upgrade.

1. Back up your database​

If you use a managed database service, your database provider may have a feature to take snapshots or otherwise back up your database. If you use the PostgreSQL subchart, run the following command to export data from the PostgreSQL pod to a .sql file.

kubectl exec -it <POSTGRES-POD-NAME> -- bash -c 'pg_dump hammerhead_production --no-acl --no-owner --clean -U postgres' > retool_db_dump.sql

2. Select a new version​

Update the image.tag value in values.yaml to the Docker tag for the version of Retool to install, such as tryretool/backend:X.Y.Z-stable.

3. Upgrade instance and apply changes​

Always upgrade your deployment to use the latest version of Retool's Helm chart. The latest version is .

Run helm search repo retool/retool to check the current version of Retool's Helm chart that is installed. Use helm upgradeto then upgrade the Helm chart version, if required.

Upgrade Retool Helm chart version
helm upgrade -f values.yaml my-retool retool/retool --version

4. Verify instance​

Run kubectl get pods to verify that the update has completed.

my-retool-7898474bbd-pr8n6               1/1     Running   1 (8h ago)   8h
my-retool-jobs-runner-74796ddd99-dd856   1/1     Running   0            8h
my-retool-postgresql-0                   1/1     Running   0            8h

You should see additional services for workflows, such as workflows-worker, workflows-backend, and code-executor.