Getting started
Quickstart
On this page
Run Claude Code in a sandbox on a throwaway project, see one change it makes to your files, then stop and remove the sandbox.
$ brig doctor ok host macOS 26.7 on arm64 ok runtime hull <version> at /opt/homebrew/bin/hull ok verify cosign at /opt/homebrew/bin/cosign, BRIG_VERIFY=warn ok profiles 9 built in, 0 in /Users/you/.config/brig ok secrets keychain reachable $ mkdir -p ~/code/demo $ brig run claude ~/code/demo brig: image and boot assets verified $ cat ~/code/demo/hello.txt hello from the sandbox $ brig stop claude $ brig rm claude
Before you start #
- Brig is installed. See Install.
- You have an Anthropic account, to log Claude Code in. With no account, use the ubuntu shell.
On macOS 15 or newer, nothing else is needed. On macOS 14, set these two variables in the terminal you use for every step:
export BRIG_HYPERVISOR=vz BRIG_NETWORK=sharedPlatform support explains why.
After the default install for the whole machine, run every brig command as root: sudo brig doctor, sudo brig run .... A rootless install runs brig as your own user. See Linux.
Every command below runs in a terminal on your host, unless a step says otherwise.
Check the host #
brig doctorBrig prints one line per check. Versions and paths differ on your host:
ok brig v0.5.2 (<commit>, <date>, <go version>, darwin/arm64)
ok host macOS 26.7 on arm64
ok virtual Hypervisor.framework available
ok runtime hull <version> at /opt/homebrew/bin/hull
-- broker not started; brig starts /opt/homebrew/bin/brig-broker on the first run with a route
!! boot assets missing at /Users/you/.hull/store/assets
run any agent once to fetch them, or set BRIG_BOOT_ASSETS to a directory that has them
ok rootfs overlay root available
ok verify cosign at /opt/homebrew/bin/cosign, BRIG_VERIFY=warn
ok profiles 9 built in, 0 in /Users/you/.config/brig
ok secrets keychain reachable
-- brigd not running (no socket at /Users/you/.brig/brigd.sock)
-- image pass an agent to check its image: brig doctor claudeok is a pass, -- is information, and !! is a failure with its fix on the next line. Before the first run, !! on the boot line is normal: the first run fetches the boot assets. Any other !! line names its fix.
Start the agent #
mkdir -p ~/code/demo
brig run claude ~/code/democlaude is the default session of the claude-code agent. ~/code/demo is the project. Brig mounts it read-write at /work/demo in the sandbox, and the agent starts there.
Before the agent starts, Brig prints what applies to this run:
- On a terminal, the first run asks once whether Brig can send anonymous usage events. Nothing is sent until you answer. See Telemetry.
- The first run downloads the guest image and the boot assets, and caches them. Later runs start faster.
- A note says that the guest home is temporary, and that
brig rmdeletes it. - When a secret store is available, Brig lists the optional secrets the agent runs without. The run continues.
- One line says that the signatures verified:
brig: image and boot assets verified.
Claude Code then asks you to log in, because the sandbox holds no login. Follow its prompts inside the sandbox, as on a new machine. For claude-code, Brig keeps this login in memory, so brig stop discards it and the next run asks again. To start logged in every time, see Authentication.
See the change on the host #
Type this instruction into Claude Code:
Create hello.txt containing "hello from the sandbox".Exit Claude Code. Then, on the host:
cat ~/code/demo/hello.txtThe project is your real directory, not a copy, so everything the agent writes in /work/demo is in ~/code/demo. The agent can also change or delete any file there.
The sandbox keeps running after the agent exits, so a second brig run claude starts at once. brig ls lists it:
REF SANDBOX STATE WORKSPACE
claude-code brig-claude-code running /Users/you/.brig/homes/brig-claude-codeWORKSPACE is the guest home: the host directory the sandbox mounts as the agent's home, for its settings and history.
Stop and remove #
brig stop claudebrig stop stops the sandbox. The session, its guest home and the project stay. The next brig run claude boots it again with the same project.
brig rm claudebrig rm removes the sandbox and deletes the guest home that Brig created. It prints the guest home it deleted and the project it left:
brig: ↳ the project /Users/you/code/demo stays on the hostNeither command touches ~/code/demo. Delete it yourself when you no longer need it. What survives lists what each command keeps.
No Anthropic account #
ubuntu is a root shell with no login. Use it in place of claude in each step:
brig run ubuntu ~/code/demoThe shell starts in /work/demo. Type these at the shell prompt, inside the sandbox:
echo "hello from the sandbox" > hello.txt
exitbrig-sh does not publish the ubuntu image, so Brig cannot verify its signature. It says so, and boots it:
brig: image docker.io/library/ubuntu:latest is not published by brig-sh, so there is no signature of ours to check
brig: boot assets verifiedThen continue with cat ~/code/demo/hello.txt, brig stop ubuntu and brig rm ubuntu.
Next steps #
- Authentication: start the agent logged in, or give it Git access.
- Sessions: run several sessions, and keep a guest home.
- Policies: restrict what the sandbox can reach.
- Troubleshooting: organized by what you saw on the terminal.