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 without a Terraform blueprint, which provisions all required infrastructure and deploy Retool via Helm automatically.
Use this guide to manually deploy Retool with the Helm package manager.
| Requirement | Details |
|---|---|
| Retool license key | Obtain from the Retool self-hosted Portal or your account manager. |
| Kubernetes cluster | Amazon EKS, Google GKE, or Azure AKS. |
| Helm | Helm 3.3.1 or later. |
| kubectl CLI | A working kubectl installation connected to your cluster. |
| PostgreSQL database | An 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 storage | S3, Azure Blob, or GCS. Used for app storage, Git repositories, and sandbox snapshots. See Configure blob storage. |
| Wildcard DNS (optional) | Only needed if you opt into a dedicated agent sandbox proxy subdomain. The default same-origin setup routes the sandbox through your existing domain and needs no wildcard DNS. See Configure networking. |
| Wildcard TLS certificate (optional) | Only needed for the dedicated proxy subdomain. Same-origin uses your existing certificate. See Configure networking. |
| Temporal | Required for Workflows and agent sandbox orchestration. Retool-managed Temporal Cloud is recommended. |
| Custom seccomp profile | The agent sandbox (gVisor) and js-executor (NsJail) both require a custom seccomp profile on each node. Amazon EKS and Google GKE support this by default. Azure AKS only officially supports the default seccomp profiles (RuntimeDefault and Unconfined). Verify your cluster permits custom seccomp profiles before deploying. Locked-down enterprise clusters and Amazon ECS do not support this. |
Additional configuration for Amazon EKS Karpenter
Karpenter requires additional configuration changes for it to support Retool's agent sandbox architecture. This is because the agent-sandbox-job pods use an extended resource (smarter-devices/net_tun) that Karpenter cannot schedule correctly.
You must run Karpenter v1.7.0 or later with the alpha nodeOverlay feature gate enabled, then create a NodeOverlay custom resource. Refer to the NodePool and EC2NodeClass resources in this reference configuration.
Additional configuration for Google Kubernetes Engine
GKE requires additional configuration changes for it to support Retool's agent sandbox architecture. This is because the default device plugin priority class, rr.agentSandbox.devicePlugin.priorityClassName, is set to system-node-critical. This prevents the agent-sandbox-device-plugin DaemonSet pods from scheduling without a custom ResourceQuota to use this PriorityClass in user namespaces.
You must set this PriorityClass to null in your values.yaml:
rr:
agentSandbox:
devicePlugin:
priorityClassName: null
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.
- Retool-managed cluster
- Self-managed cluster
- Local cluster
Recommended
You should use a Retool-managed cluster if:
- You don't have an existing cluster that 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.
If you want to create a new, self-hosted cluster on Temporal Cloud, sign up first. Once your account is provisioned, you can then deploy self-hosted Retool.
Temporal Cloud supports 10+ AWS regions from which to select, 99.99% availability, and 99.99% guarantee against service errors.
You should use an existing self-managed cluster, hosted on Temporal Cloud or in your own infrastructure, if:
- You cannot use a Retool-managed cluster.
- You have an existing cluster and would prefer to use another namespace within it.
- You need a cluster for uses other than a self-hosted Retool deployment.
- You want to manage the cluster directly.
- You have a multi-instance Retool deployment, where each instance would have its own namespace in a shared self-hosted Temporal Cluster.
Self-managed cluster considerations
Retool recommends using a separate datastore for the Workflows Queue in production. Consider using AWS Aurora Serverless V2 configured to an ACU (cpu) provision ranging from 0.5 to 8 ACU. 1 ACU can provide around 10 QPS (roughly, 5-10 concurrent blocks executed per second). The Workflows Queue is write-heavy (around 100:1 write to read operations) and Aurora Serverless can scale to accommodate spikes in traffic without any extra configuration.
Environments
For test environments, Retool recommends using the same database for the Retool Database and Workflows Queue. Without any extra configuration, Retool Workflows can process approximately 5-10 QPS (roughly, 5-10 concurrent blocks executed per second).
Workflows at scale
You can scale self-hosted Retool Workflow-related services to perform a high rate of concurrent blocks per second. If your deployment needs to process more than 10 workflows per second, you can use:
- A Retool-managed cluster.
- A self-managed cluster on Temporal Cloud.
- Apache Cassandra as the Temporal datastore.
If you anticipate running workflows at a higher scale, please reach out to us to work through a deployment strategy that is best for your use case.
You should spin up a new cluster alongside your self-hosted Retool instance if:
- You cannot use a Retool-managed cluster.
- Your organization is on the Free, Team, or Business plan.
- You don't have an existing cluster to use.
- You don't need a cluster for uses other than a self-hosted Retool deployment.
- You want to test a self-hosted Retool deployment with a local cluster first.
- You have a multi-instance Retool deployment, but each instance is in its own VPC and requires its own self-hosted Temporal Cluster.
Local cluster considerations
Retool recommends using a separate datastore for the Workflows Queue in production. Consider using AWS Aurora Serverless V2 configured to an ACU (cpu) provision ranging from 0.5 to 8 ACU. 1 ACU can provide around 10 QPS (roughly, 5-10 concurrent blocks executed per second). The Workflows Queue is write-heavy (around 100:1 write to read operations) and Aurora Serverless can scale to accommodate spikes in traffic without any extra configuration.
Environments
For test environments, Retool recommends using the same database for the Retool Database and Workflows Queue. Without any extra configuration, Retool Workflows can process approximately 5-10 QPS (roughly, 5-10 concurrent blocks executed per second).
Workflows at scale
You can scale self-hosted Retool Workflow-related services to perform a high rate of concurrent blocks per second. If your deployment needs to process more than 10 workflows per second, you can use:
- A Retool-managed cluster.
- A self-managed cluster on Temporal Cloud.
- Apache Cassandra as the Temporal datastore.
If you anticipate running workflows at a higher scale, please reach out to us to work through a deployment strategy that is best for your use case.
Cluster size
The following services add to the cluster's resource requirements. The agent sandbox job pods scale with active builder sessions:
| Component | CPU | Memory |
|---|---|---|
| js-executor | 6 cores | 6 GiB |
| r2-worker | 1 core | 2 GiB |
| agent-sandbox-proxy | ¼ core | 256 MiB |
| agent-sandbox-controller | ¼ core | 256 MiB |
| agent-sandbox-job pods (×5 default) | 5 cores | 10 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.
35.92.202.168/29
44.211.178.248/29
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
licensing.tryretool.com
invites.tryretool.com
email-service.retool.com
p.tryretool.com
specs.tryretool.com
pypi.org
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.
$ helm repo add retool https://charts.retool.com
Run helm search repo retool/retool to confirm you can access the Retool chart.
NAME CHART VERSION APP VERSION DESCRIPTION
retool/retool 6.11.4 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.
| Setting | Description |
|---|---|
config.licenseKey | License key, in plain text or as a secret value. |
config.encryptionKey | Key used to encrypt the database. Generate a random string with openssl. |
config.jwtSecret | Secret used to sign authentication requests from Retool's server. Generate a random string with openssl. |
image.tag | Version 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.useInsecureCookies | Whether 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.enabled | Whether to enable Retool Workflows. Set to true. Defaults to true for Retool version 3.6.14 or later. |
codeExecutor.enabled | Whether 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.enabled | Whether 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.postgresql | Details 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.86.1-stable — all services must run the same tag.
image:
tag: X.Y.Z-stable # use the tag shown above — all services must match
rr:
enabled: true # master switch: enables agent, js-executor, agent-sandbox, and git server
agentSandbox:
externalSecret:
name: 'agent-sandbox-env'
postgres:
schema: 'agent_executor'
proxy:
backendDomainSuffixes: "yourdomain.com"
gitServer:
enabled: true
mcp:
enabled: true # optional; requires separate OAuth config; NOT part of rr.enabled
The agent sandbox is served same-origin through your existing Retool ingress, and you do not set frontendWsProxyDomain or a dedicated proxy subdomain. To run the proxy on its own subdomain instead, see Configure networking.
Configure agent sandbox secrets
The agent sandbox requires a JWT keypair and an encryption key. It reuses the backend's Postgres connection automatically on a separate schema (agent_executor), and no connection URL is needed. When the backend uses SSL, the inherited connection automatically uses sslmode=no-verify. However, if the backend database password is injected via envFrom or an external secret, point rr.agentSandbox.postgres.urlSecretName at a secret holding the DSN.
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
# encryption key must be exactly 64 hex characters (base64 is rejected at runtime).
# tr -d '\n' drops openssl's trailing newline; without it the Secret holds 65 bytes and fails.
openssl rand -hex 32 | tr -d '\n' > 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)
EOF
kubectl apply -f agent-sandbox-env.yaml
The rr.agentSandbox.externalSecret.name set in the enable block above tells the agent sandbox where to find this Secret — no further configuration is needed.