RTK and Tokensave

[vsolodki]

Hello, can RTK and Tokensave be used when Headroom is running as a container? Or they must be installed separately? With Python installation and wrap command they are installed and configured automatically, but what about when with Docker image? Is there a way to do it?

[yhay81]

There are two different Docker cases here.

1. Docker-native wrapper (the install script): RTK can still be used. The wrapper starts the Headroom proxy in Docker, but Claude/Codex/etc. runs on the host. During the --prepare-only phase it mounts the host's ~/.headroom and agent config directories, passes the host platform as HEADROOM_RTK_TARGET, and can download the host-target RTK binary into the mounted Headroom state.

RTK is opt-in in current releases, so with the Docker-native wrapper use:

HEADROOM_RTK=1 headroom wrap claude
# or: HEADROOM_RTK=1 headroom wrap codex

The wrapper forwards HEADROOM_* variables into its preparation container. The relevant flow is in scripts/install.sh / install.ps1.

2. Running only the published proxy image: the image does not bundle RTK. This is called out in the Docker-native documentation. Starting ghcr.io/headroomlabs-ai/headroom by itself will not intercept commands executed by an agent on the host. Install/configure RTK where the agent actually executes shell commands, or use the Docker-native wrapper above. Installing RTK only inside the proxy container would not rewrite commands running on the host; it is mainly relevant if the agent also runs in that container or if you want the container's dashboard to read RTK statistics. A derived image is the clean option for that arrangement.

Tokensave is no longer something to install. It has been retired and replaced by Serena. Current headroom wrap removes a stale Headroom-managed tokensave MCP entry and registers Serena as the default code-memory MCP instead; see the current proxy docs. Use --code-memory serena (the default) or --code-memory none to disable code-memory integration.

So for the usual setup—Headroom proxy in Docker, coding agent on the host—the practical answer is: use the Docker-native headroom wrap flow with HEADROOM_RTK=1, and use Serena rather than Tokensave.