Skip to main content

Self-hosted, self-managed Retool quickstart

Learn about the fundamental concepts of a self-hosted, self-managed Retool deployment.

This guide serves as an introduction to self-hosted Retool. It covers many of the concepts and terminology you would come across when deploying and operating a self-hosted instance of Retool. After reading this page, you should have a good understanding of self-hosted, self-managed Retool.

Each instance uses a distributed set of containers with services for different functions. These work together to securely run the platform within your VPN or VPC.

Kubernetes with Helm is the officially supported production deployment configuration. For new deployments, Retool provides Terraform blueprints to provision all required infrastructure and deploy Retool via Helm automatically. Customers with existing Kubernetes infrastructure can also deploy directly using Helm.

Deployment pathProductionTestingDescription
Kubernetes + Helm Officially supported production configuration. Requires Amazon EKS.
Docker Compose For non-production, development, and proof-of-concept deployments only.

Network requirements​

Deployments must be allowed 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.

IP addresses
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
Domains
licensing.tryretool.com
invites.tryretool.com
email-service.retool.com
p.tryretool.com
specs.tryretool.com
pypi.org

Each data source you use with Retool is represented by a resource, such as APIs and external databases. Your deployment instance must have access to any of its resources to interact with data.

Temporal egress​

If you use Temporal Cloud for workflow and sandbox orchestration, your deployment must allow outbound access on the following ports:

PortDomains
443*.retool.com, *.tryretool.com, *.temporal.io
7233Your Temporal namespace endpoint. Retool-managed clusters use the format org-[sid].atdwz.tmprl.cloud, where sid is your organization's ID. Use *.tmprl.cloud if you need a wildcard rule.

Both the MAIN_BACKEND and WORKFLOW_TEMPORAL_WORKER containers require this egress. Temporal Cloud does not publish a static IP range to allowlist.

Architecture​

The following diagram shows how the containers in a self-hosted deployment interact.

Loading diagram...

Containers and services​

A standard deployment instance uses the following containers and services that interact with each other. The SERVICE_TYPE environment variable values determine the services certain containers run.

ContainerImageRepositoryServices
apibackendtryretool/backendMAIN_BACKEND
DB_CONNECTOR
DB_SSH_CONNECTOR
jobs-runnerbackendtryretool/backendJOBS_RUNNER
workflows-workerbackendtryretool/backendWORKFLOW_TEMPORAL_WORKER
workflows-backendbackendtryretool/backendWORKFLOW_BACKEND
DB_CONNECTOR
DB_SSH_CONNECTOR
code-executorcode-executor-servicetryretool/code-executor-serviceNo service type.
js-executorjs-executor-servicetryretool/js-executor-serviceNo service type.
agent-sandboxagent-sandbox-servicetryretool/agent-sandbox-serviceNo service type.

api​

The api container manages the core functionality for a Retool instance, such as:

  • Frontend interactions (e.g., building apps and workflows).
  • Hosting apps and workflows.
  • Managing users and permissions.
MAIN_BACKEND

The core service for a Retool deployment instance. It handles most logic for frontend interactions.

DB_CONNECTOR

Handles query requests to resources (databases, APIs, etc.).

DB_SSH_CONNECTOR

Manages connections for DB_CONNECTOR.

jobs-runner​

The jobs-runner container manages background tasks, runs database migrations for Retool version upgrades, and Source Control.

JOBS_RUNNER

Performs database migrations and manages Source Control.

workflows-worker​

The workflows-worker container continuously polls the Temporal Cluster for tasks required to either start or execute blocks within a workflow. It makes requests to code-executor to execute blocks and process results, then reports back to Temporal to continue or complete workflow execution.

WORKFLOW_TEMPORAL_WORKER

Polls the Temporal Cluster for tasks required to start or execute workflow blocks.

workflows-backend​

The workflows-backend container receives and processes requests from code-executor to process workflows. It also handles the upload of workflows logs, block results, and run status updates.

WORKFLOW_BACKEND

Handles query, retry, and asynchronous logic.

DB_CONNECTOR

Handles query requests to resources (databases, APIs, etc.).

DB_SSH_CONNECTOR

Manages connections for DB_CONNECTOR.

code-executor​

The code-executor container executes single block runs from the Workflows IDE, multiple blocks as part of a workflow execution, and any arbitrary user code written in a workflow. It executes JavaScript and Python code directly, or makes requests to workflows-backend to run resource queries against databases, APIs, etc.

By default, the code-executor uses nsjail to sandbox code execution. nsjail requires privileged container access. If your deployment does not support privileged access, the code executor automatically detects this and runs code without sandboxing.

js-executor​

The js-executor container provides a sandboxed JavaScript execution environment for backend functions. It does not require privileged container access.

js-executor does not use a SERVICE_TYPE environment variable.

agent-sandbox​

The agent-sandbox manages the app editing experience. Each active builder session runs in an isolated sandbox pod with a web server for app previews and a WebSocket connection to the builder's browser. Uses gVisor for secure isolation without requiring root access.

Internally, the agent sandbox consists of:

  • A controller that creates and destroys sandbox pods
  • A proxy that routes browser connections to the correct sandbox
  • A device plugin DaemonSet that manages sandbox resources on each node
  • An r2-worker that handles sandbox coordination
  • Per-session job pods that run the sandbox workload

A prewarm pool of idle sandbox pods (default: 5) reduces startup latency for new editing sessions. This is configurable down to 0 if cost is a higher priority than session readiness.

agent-sandbox does not use a SERVICE_TYPE environment variable. It runs as multiple cooperating pods managed by the sandbox controller.

retooldb-postgres​

You can optionally configure your deployment to use Retool Database with a separate PostgreSQL database. You can use retooldb-postgres to get started but Retool recommends you migrate to an externally hosted database for use in production.

Other dependencies​

Self-hosted deployment instances have additional dependencies.

Platform database​

Your deployment must be able to connect to the externalized platform database and have access to it.

Blob storage​

Object storage is required for app storage, Git repository storage, and agent sandbox snapshots. This is the only stateful dependency that is not automatically provisioned — you must configure it via environment variables or an in-product setup flow.

Supported providers:

  • Amazon S3 (IAM keys or IAM roles)
  • Azure Blob Storage
  • Google Cloud Storage (service account keys)

For Docker Compose deployments, a bundled MinIO container provides local blob storage suitable for development and POC environments.

Resources​

Each data source you use with Retool is represented by a resource, such as APIs and external databases. Your deployment instance must have access to any of its resources to interact with data.

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.

In general, Retool recommends using a Retool-managed Temporal Cluster. You can also use either:

  • A self-managed external cluster: Either Temporal Cloud or self-hosted within your infrastructure.
  • A local cluster: A self-hosted cluster within your self-hosted Retool instance.
Retool-managedself-managed externalLocal
HostingExternally on Temporal CloudEither externally on Temporal Cloud or self-hosted internally within your own VPCLocally as part of the self-hosted Retool instance
AvailabilityAll self-hosted Retool instances (3.6.14+) on an Enterprise planAll self-hosted Retool instances and for purposes outside of Retool.Only to the self-hosted Retool instance
ManagementManaged by Retoolself-managed on Temporal Cloud, self-managed and self-hosted if within your own VPCself-managed and self-hosted
Scale and performanceAt least 4 AWS regions are available to choose fromIf using Temporal Cloud, at least 10 AWS regions are available to choose from; if self-hosted, low latency due to hosting within your infrastructureLow latency due to local deployment alongside self-hosted Retool
Uptime99.99% uptime99.99% uptimeDependent on DevOps
ConfigurationMinimalModerateHigh
CostNo minimum contractSee Temporal Cloud pricingNo contract
SecurityResource-isolated namespace in a Temporal Cloud cluster, in which only orchestration data (workflow IDs and block names) is stored; all data encrypted with private keyOnly orchestration data (internal Workflow IDs, and encrypted Workflow block names, user IDs, Workflow name, host name, and base domain), is stored in Temporal Cloud. All other data remains internal on VPC for self-hosted.All data remains local to the self-hosted Retool instance

Temporal is also required for agent sandbox lifecycle orchestration. Two options are supported:

  • Temporal Cloud (recommended) — stores only encrypted job coordination metadata; no customer data leaves your deployment's encryption boundary
  • BYO Temporal — customer-managed; Retool does not provide support for this option

Configure Temporal via the in-product setup in the Workflows section after deploying.

Docker images​

Retool uses Docker images that configure the containers and their respective services. Each container runs one or more services to distribute functionality. This approach allows for efficient scaling of a Retool deployment instance as needs grow.

Retool maintains image repositories on Docker Hub:

Each Docker Hub repository tag corresponds to a particular version of Retool. You specify the version to use when deploying or upgrading a release. For instance:

  • tryretool/backend: X.Y.Z-stable

  • tryretool/code-executor-service: X.Y.Z-stable

Always use the same version number across every image.

Releases​

Retool maintains two release channels for self-managed Retool: Stable and Edge.

Retool releases a version on the stable channel each quarter. A stable release is generally four versions behind the cloud-hosted version at the time.

Preparation and testing of a stable version occurs approximately four weeks prior to its release. Stable releases are rigorously tested before they are published. As the release cycle is less frequent, administrators can more easily maintain and upgrade deployments.

Retool supports each stable release for six months. During this time, Retool will release patch updates that contain bug fixes or security updates. Patch updates do not contain functionality changes and can be applied more quickly than performing a full version upgrade.

Retool provides versioned product documentation for supported stable releases. When browsing Retool Docs, use the version dropdown menu in the navbar to switch to a relevant version.

After six months, a stable release is considered deprecated. You can continue using a deprecated release but it will no longer receive updates. At this time, you should upgrade to the latest stable release.