Hardened images for self-hosted Retool

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

Hardened images Availability
Self-hosted Edge 3.307.0-edge-hardened-beta or later	Public beta	Available on all plans
Self-hosted Stable Expected in Q1 2026.

Self-hosted instances can use hardened images, which are available on the edge release channel. 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.

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.

Classic images remain supported, and you can continue using them if hardened images do not fit your requirements. Over time, Retool plans to make hardened images the default for self-hosted deployments.

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.

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 first released on the edge channel as beta builds. Tags use the following pattern: X.YYY.Z-edge-hardened-beta, where X.YYY.Z matches the corresponding edge 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 edge release notes.

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

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

Some customers 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 Deployment 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.

If you currently use MSSQL with Windows Authentication, you should continue using classic images while Retool determines the long-term support model for Windows Authentication.

code-executor and other workloads

Many customers also run the separate code-executor service.

While hardened images are in public beta:

• Hardened images are available for core backend services first.
• A hardened code-executor-service image is under active development and may not yet be available for your version.
• You may therefore have a mixed environment where core backend services use hardened images, while some auxiliary services (such as code-executor) continue to use classic images.

This mixed setup is expected and supported during the public beta. 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, including code-executor.

Retool is actively working to expand arm64 coverage across all services.

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 edge 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.