Skip to main content

Hardened images for self-hosted Retool

Learn about hardened images for self-hosted Retool, including security changes, ARM64 support, and migration guidance.

Hardened image rollout

Refer to the changelog for more information about hardened images, including feature impact announcements as the rollout continues. Hardened images become the default for self-hosted instances in Q2 2027.

Self-hosted instances can use hardened images, which are available on the edge release and stable release channels. These images are designed to improve supply-chain security, reduce the attack surface, and support modern infrastructure while remaining functionally compatible with existing deployments.

Refer to the changelog entry for hardened images for information about how to transition to using hardened images.

This guide explains what hardened images are, how they differ from classic images, and what to consider before adopting them in your environments.

note

Hardened images are available for the tryretool/backend and tryretool/code-executor-service Docker images.

If you deploy with Docker Compose, hardened images require Docker Engine 24.0.7 or later.

Hardened vs. classic images​

Hardened images introduce several changes compared to the existing classic Docker images:

  • Chainguard-based, Wolfi OS images: Hardened images use a minimal Wolfi base and are patched and maintained through Chainguard. System-level packages are curated and updated to reduce known vulnerabilities and tighten supply-chain security.

  • Multi-architecture support: Hardened images are published as multi-architecture Open Container Initiative (OCI) images that support both amd64 and arm64. When you run them on arm64 nodes, you can often reduce compute requirements and improve performance compared to equivalent amd64 instances.

  • Bazel-built OCI images instead of Dockerfiles: Hardened images are built using Bazel, which assembles OCI layers directly instead of using traditional Dockerfiles. This enables finer-grained control over file layout, permissions, and dependencies.

Image repositories and release channels​

Hardened images use the same repositories as classic images: tryretool/backend for most backend services such as api, jobs-runner, and workflow workers, and tryretool/code-executor-service for the code-executor service.

Refer to the self-hosted architecture guide for an overview of how these images map to containers and services.

Hardened image tags​

Hardened images are released on the edge or stable channel. Tags use the following pattern: X.YYY.Z-edge-hardened or X.YYY.Z-stable-hardened, where X.YYY.Z matches the corresponding standard version for classic images.

The changes available on the hardened image tag contain the same changes as the classic images. These changes can be found in the release notes.

Classic tags (for example, X.YYY.Z-edge) continue to be published alongside hardened tags, and you can choose which series to deploy.

Deploying hardened images with Helm​

To deploy hardened images on Kubernetes with Helm, set image.tag in values.yaml to a hardened tag:

image:
  tag: "4.34.6-stable-hardened"
codeExecutor:
  enabled: true

With codeExecutor.enabled set to true, the chart automatically deploys the matching hardened tryretool/code-executor-service tag, so you don't need to set codeExecutor.image.tag separately in the common case.

After changing image.tag, run helm upgrade to apply the change.

Changes that may affect your deployment​

Hardened images are intended to be functionally compatible with classic images, but there are some important behavioral and operational differences to be aware of.

System dependency packages​

Hardened images include a smaller, more controlled set of system dependency packages at the OS level. Examples of system dependencies include tools like curl or ssh, or other utilities installed by the base image.

In classic images, some tools may be present because of the underlying distribution or how the image is built. With hardened images:

  • System dependencies are explicitly curated and patched.
  • Extra tools that Retool does not depend on are removed where possible.
  • Newly added dependencies are evaluated for security and long-term support.

For broader security recommendations, refer to Security hardening best practices.

Modified or custom Retool images and debugging tools​

You can optionally extend Retool images to add additional packages or tools, or rely on interactive debugging inside the containers. For example:

  • Building a custom Docker image FROM tryretool/backend and running apt-get install ....
  • Baking extra utilities directly into the containers.
  • Opening a shell in a Retool container to run ad-hoc debugging commands.

Hardened images significantly change how these patterns work:

  • The underlying OS is no longer Debian-based; common tools like apt are not available.
  • Image layers are generated by Bazel, and the file layout, users, and permissions may differ from classic images.
  • Directly modifying hardened images can bypass many of the security benefits they provide.
  • Nonessential system utilities are removed, so you may see fewer CLI tools available and different default users/permissions compared to classic images.

Retool does not recommend, and cannot support, building custom images that modify hardened Retool images in place. If you have additional runtime or debugging needs:

  • Prefer running sidecar containers or separate services that you control.
  • If you must create a custom assembly that embeds Retool, use a workflow that is compatible with Wolfi/Chainguard images and follows their security guidance.
  • Keep custom tooling off the main Retool containers whenever possible.
  • Use centralized logging and observability tools, such as those described in Container logs and Collect self-hosted telemetry data.
  • Run debugging tools from separate admin or bastion hosts rather than from within Retool containers.

If you currently rely on custom Retool images or in-container debugging workflows, plan for additional validation and manual changes when testing hardened images.

MSSQL with Windows Authentication​

The only known product feature not currently supported in hardened images is Microsoft SQL Server with Windows Authentication. This configuration is complex to maintain and introduces additional security and build performance considerations.

Windows Authentication for MSSQL is deprecated. If you use MSSQL with Windows Authentication, migrate your resources to SQL Server authentication.

code-executor and other workloads​

You can also deploy and run a hardened code-executor-service container, which uses the same Chainguard/Wolfi base, Bazel-built OCI layers, and curated system packages as the hardened backend image.

Other services, such as js-executor-service and agent-sandbox-service, don't have hardened images yet. If you deploy hardened backend and code-executor-service images, you may therefore have a mixed environment where these other services continue to use classic images. This mixed setup is expected, and you can gradually migrate each workload to hardened images as they become available, starting with non-production environments.

Infrastructure and arm64 considerations​

Hardened images are published as multi-architecture images that support both amd64 and arm64. However, full support for an end-to-end arm64 deployment depends on hardened images being available for all required services. js-executor-service and agent-sandbox-service don't have hardened, arm64-compatible images.

Frequently asked questions​

Refer to the following frequently asked questions.

Do hardened images change how Retool behaves?​

Hardened images are intended to be functionally equivalent to classic images for supported features. Most differences are at the OS, packaging, and security hardening layers.

You should not see changes to how apps, workflows, or queries behave, aside from:

  • Unsupported configurations such as MSSQL with Windows Authentication.
  • Any custom tooling or workflows that rely on incidental OS tools inside the containers.

Can I switch between classic and hardened images?​

Yes. Because hardened images share the same underlying product version as classic images, you can:

  • Upgrade from classic to hardened images on a given version.
  • Roll back to classic images on that same version if necessary.

Always follow the guidance in Upgrade deployments when changing image tags, and test changes on non-production instances first.