Confined use

The Contract

Gantry's built-in profile is a process fence: it gives spawned agent and MCP tool processes a private PID namespace, parent-death behavior, and a main-checkout write guard for run correctness. It keeps the host filesystem writable and visible, uses the operator's user account, and does not block credentials, home-directory reads, temporary storage, or network egress.

Confinement comes from putting Gantry inside an external boundary and making that boundary the authority. GANTRY_SANDBOX_CMD is the per-agent wrapper hook for user-supplied boundaries, but it is only one spawn hook: Gantry's own engine, setup commands, git operations, harness binaries, package managers, and any commands those tools launch must also be inside the boundary if they are part of the risk.

Boundary Contents

• The project repository and any sibling Gantry worktrees under .gantry-worktrees/.
• The per-plan run artifacts under .gantry/<plan>/, including logs, prompts, reports, attach sockets, and process rosters.
• Gantry user configuration and runtime locations, including ~/.config/gantry, $GANTRY_CONFIG, $XDG_RUNTIME_DIR, and Gantry's secure temp-dir fallback.
• Harness binaries and their authentication stores, for example Claude, Codex, Gemini, and OpenCode config, OAuth, and token files.
• Temporary storage such as /tmp, package caches, language build caches, and tool-specific state.
• Commands Gantry runs itself, commands the selected harness runs, and commands an agent asks a shell, MCP tool, package manager, test runner, or build tool to run.
• Fresh-machine authentication through auth_env entries in .env.gantry or ordinary token environment variables.

Network egress control belongs to that boundary and never to Gantry. If a run must be offline, the machine, VM, container, firewall, proxy, or network namespace has to enforce it.

Recipes

Dedicated low-trust machine or VPS

Clone the project onto a machine that holds only the source, tools, tokens, and cache state you are willing to expose to the run. Authenticate harnesses there, or provide short-lived tokens through .env.gantry / environment variables. This boundary contains the whole OS user account and its network policy. It does not protect anything else reachable from that machine or from tokens you install there.

Container, devcontainer, or Podman workspace

Build an image with Gantry, git, the selected harness CLIs, language toolchains, and any package caches you choose to mount. Mount the repository and .gantry-worktrees/ inside the container, provide harness auth through mounted secrets or environment variables, and run Gantry from inside the container. This boundary contains filesystem mounts, temp storage, process limits, and network egress only to the extent the container runtime is configured to enforce them. Gantry does not add network policy inside it.

Custom per-agent wrapper

Set GANTRY_SANDBOX_CMD to a wrapper such as a container, VM, namespace, or policy launcher when the engine may stay outside but agent subprocesses need an extra boundary. The wrapper must expose the run worktree, the canonical checkout paths needed by git, Gantry's runtime sockets, harness binaries, and harness auth. It does not contain Gantry's own engine process or commands run before or after the agent spawn unless you launch Gantry itself inside the same external boundary.