brig docs

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
The quickstart in six commands, with lines from the steps below.

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=shared

Platform 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 doctor

Brig 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 claude

ok 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/demo

claude 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 rm deletes 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.txt

The 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-code

WORKSPACE 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 claude

brig 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 claude

brig 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 host

Neither 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/demo

The shell starts in /work/demo. Type these at the shell prompt, inside the sandbox:

echo "hello from the sandbox" > hello.txt
exit

brig-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 verified

Then 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.

Type a command, a flag or an error message.