Getting started

Quickstart

On this page

Prerequisites
Host check
First run
Agent files
Success check
Stop and remove

This quickstart runs Claude Code in a sandbox on a throwaway project, then stops the sandbox. The sample output is from macOS. The same steps apply on Linux.

$ brig doctor
  ok  host      macOS 26.5 on arm64
  ok  virtual   Hypervisor.framework available
  ok  runtime   hull <version> at /opt/homebrew/bin/hull
  ok  verify    cosign at /opt/homebrew/bin/cosign, BRIG_VERIFY=warn
  ok  profiles  8 built in, 0 in /Users/you/.config/brig
  ok  secrets   keychain reachable
$ mkdir -p ~/code/demo && cd ~/code/demo
$ brig run claude ~/code/demo
brig: image and boot assets verified
$ brig stop claude
$ brig rm claude

The quickstart in five commands. The output is the sample output from the steps below.

Prerequisites #

Install Brig first. Install covers each platform. If the host runs macOS 14, set the two variables in Platform support before you run an agent.

Host check #

brig doctor

Brig prints one line per check:

  ok  host      macOS 26.5 on arm64
  ok  virtual   Hypervisor.framework available
  ok  runtime   hull <version> at /opt/homebrew/bin/hull
  !!  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  verify    cosign at /opt/homebrew/bin/cosign, BRIG_VERIFY=warn
  ok  profiles  8 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

Mark	Meaning
`ok`	Brig found what that line checks.
`!!`	Brig prints a fix beside the line. It does not stop you here.
`--`	Brig looked and found nothing to report. This is not a failure.

Three lines in the sample need a note:

virtual reports only whether this Mac can host a microVM. It does not say which backend a run uses.
boot shows !! before the first run. Brig fetches missing boot assets the first time an agent needs them.
brigd is an optional daemon. This quickstart does not need it.

First run #

mkdir -p ~/code/demo && cd ~/code/demo
brig run claude ~/code/demo

claude is the default session of the claude-code agent. ~/code/demo is the project this run mounts.

Downloads #

The first run downloads the guest image and the boot assets (the kernel and the initrd). Brig caches both, and later runs reuse them.

Situation	What Brig prints for each download
On a terminal	A spinner while the download runs
stderr redirected, the run in the background, or `TERM=dumb`	One line when the download starts, and another when it completes
The download fails	The error

With nerdctl on Linux, only the boot assets are announced. nerdctl pulls the image without a notice from Brig.

Execution envelope #

brig --verbose run prints the execution envelope before it boots. brig info claude prints the same envelope and runs nothing:

PROFILE      claude-code
SANDBOX      brig-claude-code (hull)
ISOLATION    microVM (hull, hvi backend)
WORKSPACE    /Users/you/.brig/homes/brig-claude-code (read-write)
IMAGE        ghcr.io/brig-sh/claude-code-stock:root (pull missing)
VERIFY       warn, against brig's own trust policy
CREDENTIALS  (none)
NETWORK      isolated (a network of this sandbox's own)

Field	Meaning
`ISOLATION`	`claude-code` asks for hull's `hvi` backend. `hvi` drives Apple's Hypervisor.framework directly, not Virtualization.framework.
`WORKSPACE`	The CLI's label for the guest home.
`NETWORK`	The `isolated` network keeps the new sandbox off the networks of other sandboxes. It allows internet access.

Existing sessions and their network

An existing session keeps its recorded network. A session with no record reports the posture that Brig reads from the runtime. An older shared session can therefore still report shared.

On macOS, hull can ask one question about telemetry before the agent appears. See Telemetry for what it counts and how to turn it off.

After Brig verifies the image and the boot assets, it prints one line and starts the sandbox:

brig: image and boot assets verified

Then Claude Code asks you to log in inside the sandbox, because the sandbox holds no credential. On claude-code, brig stop removes the login, and the next run asks again.

Agent files #

The sandbox mounts two host directories.

Directory	Host path	In the sandbox
Guest home	`~/.brig/homes/brig-claude-code`	Mounted as the agent's home. The agent's settings and history live there.
Project	`~/code/demo` in the run above	Mounted read-write at `/work/demo`. The agent starts there.

The agent works on your real files under /work/demo, so its changes land in your project. Your keychain, your SSH agent and every host directory you did not name stay out of its reach.

Sessions describes the guest home, the project, and what survives each command for each agent.

Success check #

The agent's prompt appears. Inside it, pwd prints /work/demo.

While the agent runs, the sandbox stays up, so a second brig run claude is immediate.

Stop and remove #

brig stop claude   # stop the sandbox, keep its name
brig rm claude      # stop and remove it

Command	Effect
`brig stop`	Stops the sandbox. Keeps its name, its row in `brig ls`, and what Brig recorded about the session.
`brig rm`	Stops the sandbox and drops all of that too. Deletes `~/.brig/homes/brig-claude-code`.

Neither command touches ~/code/demo.

If a run does not do what you expected, see Troubleshooting. It is organized by what you saw on the terminal.