Agent shell

Minimal can sandbox AI coding agents the same way it sandboxes your dev tools: an agent runs inside a session, with access to your source code and only the tools and host state you declare.

Example: Claude Code

This documentation site is itself built and maintained using Claude Code inside a Minimal session. Add the agent’s package to the project’s [session] block:

[session]
packages = ["claude-code", "base"]

Then activate the session and run the agent inside it:

$ min session activate --attach .
$ claude

Claude Code launches inside the session with your project’s source code and a read-only system containing the claude-code binary and core utilities from base. The session has no additional access to anything on your host system unless you explicitly declare it.

Note that sessions are driven interactively: attaching needs a terminal. Launch the agent from inside an attached shell as shown above, rather than scripting it from the host.

Adding more tools

Agents often need additional tools to be effective. Add packages to the [session] block just like any other:

[session]
packages = ["claude-code", "base", "git", "curl"]

Passing through host credentials

Use patches to give the agent access to host files it needs, like authentication state. Each patch maps a host source to a dest under the session user’s home directory:

[session]
packages = ["claude-code", "base", "git"]
patches = [
    { source = "~/.gitconfig", dest = "~/.gitconfig" },
    { source = "~/.ssh",       dest = "~/.ssh" },
]

Environment variables can be inherited from the host as well, under [session.vars]:

[session.vars]
ANTHROPIC_API_KEY = { inherit = true }

Anything you pass through is available to the agent and to any code it runs: a patched ~/.ssh means the agent can use your SSH keys, and an inherited ANTHROPIC_API_KEY is readable by every process in the session. Pass through the minimum the agent needs, and prefer scoped or short-lived credentials over long-lived ones. Activation helps you hold this line: each value inherited from your environment and each file patch is gated against your user policy, and anything your policy cannot decide is surfaced for approval before it enters the session.

Why sandbox agents?

Running an AI agent in a Minimal session means it can only access the tools and files you declare. It cannot install arbitrary software, read unrelated files, or modify your system. This is the same isolation model that Minimal applies to builds and dev shells, applied to agents.