Pass environment variables in

The sandbox clears the environment and forwards a small built-in allowlist. A variable set in your container terminal is not automatically available to the agent.

Forward a variable

Add names to the sandbox config:

pass-env = MY_SERVICES_PATH, MY_FIXTURE_DIR

With the PyPI launcher, use the host’s ~/.config/claude-sandbox.conf; see container configuration for mounting it. In your own devcontainer, edit /etc/claude-sandbox.conf outside the agent.

These are names, not assignments. Values must exist in the environment that launches the agent inside the container. The host launcher forwards CLAUDE_SANDBOX_* variables at container creation; it does not forward arbitrary host variables. To supply one interactively:

In your devcontainer terminal, skip the first line and run the second directly.

claude-sandbox shell        # Skip if already in your devcontainer terminal
MY_FIXTURE_DIR=/workspaces/fixtures CLAUDE_SANDBOX_PASS_ENV=MY_FIXTURE_DIR claude

Exit the shell when finished if you opened it with the host launcher. Unset variables are skipped.

What crosses the boundary

Every forwarded value is readable by the agent and its tools. Avoid secrets and inspect values before allowing them. A variable naming a socket does not make that socket safe to expose; see Make extra paths writable.

The sandbox rejects overrides for its own environment and loader or shell startup hooks, including PATH, HOME, IS_SANDBOX, LD_* and BASH_ENV. See the deny-list.

Config changes apply on the next agent launch. Devcontainer reinstalls restore the shipped config, so reapply custom settings in postCreate.