Skip to content

Local‑adapter deprecation path

This is the operator runbook for the deprecation of the unsandboxed claude_local and codex_local adapters in favour of their sandboxed equivalents.

Current status as of v3.0.0

The sandboxed adapters (claude_sandbox, codex_sandbox) are shipped and are the recommended default for production. The unsandboxed local adapters (claude_local, codex_local) are still registered and continue to work for trusted single‑tenant hosts. The TRIMUS_LOCAL_ADAPTERS env gate is reserved but not yet enforced — setting it logs a line at boot but does not remove the local adapters from the registry. Plan migrations now; the enforcing gate lands in a future release.

Why the local adapters are being deprecated

claude_local / codex_local spawn the agent CLI as a child process on the Trimus host. The process inherits the host filesystem and environment (including DATABASE_URL and TRIMUS_ENCRYPTION_KEY), sees the host network, and has no container boundary. Single‑tenant dev boxes are usually fine with this; multi‑tenant production is not. See adapter-isolation.md for the full contract.

The sandboxed adapters wrap the same CLI inside a hardened Docker container: --read-only root + /tmp tmpfs, --cap-drop ALL, --security-opt no-new-privileges, --pids-limit (TRIMUS_SANDBOX_PIDS_LIMIT), --memory-swap pinned to --memory, no host env inheritance, and the trimus-egress-allowlist Docker network with deny‑by‑default DNS.

Migrating an agent: claude_local → claude_sandbox

Per‑agent; there is no global cutover.

  1. Open the agent's settings in the UI.
  2. Change Adapter from claude_local to claude_sandbox (or codex_local → codex_sandbox).
  3. Fill in the sandbox adapter config:
  4. Image — a container image that carries the claude (or codex) CLI.
  5. Memory limit — 1g suits most agents.
  6. CPU limit — 1.0 is a fine default.
  7. Save, then trigger a heartbeat manually to confirm the container starts cleanly. The first run pulls the image, which can take a few seconds.

Before the egress‑allowlist work bites, add per‑company allowlist rows for any non‑default outbound destinations at /companies/{id}/egress.

The TRIMUS_LOCAL_ADAPTERS gate

Today the variable is reserved but not enforced — setting it writes a boot log line so you can confirm it's read, but the local adapters still register. Expected boot log when set:

{"level":"INFO","msg":"TRIMUS_LOCAL_ADAPTERS reserved"}

When unset (the common case) the engine logs nothing. In a future release TRIMUS_LOCAL_ADAPTERS=disabled will remove the local adapters from the registry at boot and refuse to dispatch heartbeats for agents still configured for them, with a clear migration message.

What to do today

  • Single‑tenant dev: nothing — keep using claude_local / codex_local if you like.
  • Multi‑tenant production:
  • Migrate agents to claude_sandbox / codex_sandbox (or docker with a custom image). Verify none still reference the local adapters.
  • Optionally set TRIMUS_LOCAL_ADAPTERS=disabled in your env file now as the explicit "we don't want the unsandboxed adapters" signal. It's a no‑op today, but future‑proofs the deploy so it won't regress when the gate becomes enforcing.

Cross‑references