brig docs

Getting started

Brig documentation

On this page

Brig gives a coding agent a machine of its own: a microVM on your computer. You decide what the agent can read, write and reach.

brig run claude ~/code/demo
What brig run does Four steps. You name an agent and a project with brig run claude ~/code/demo. Brig checks the image signature. A microVM boots with its own kernel. The agent starts in your project at /work/demo. 1 You name an agent and a project. 2 Brig checks the image signature. 3 A microVM boots with its own kernel. 4 The agent starts in your project. /work/demo
What one brig run does.

Let the agent run unattended. It works in the project you name, and the rest of your machine is out of its reach. When you are done, remove the sandbox and start clean.

InstallHomebrew, install.sh, Linux, or a source build. How to verify a download. QuickstartOne agent on a throwaway project, start to finish. Security modelWhat you control, and where each boundary sits. Command lineEvery verb, flag, environment variable and exit code.

See it run #

Claude Code in a sandbox. It writes and runs a file in the project, and the file is on the host afterwards.
A real session, recorded on macOS. Claude Code sees the project and nothing else from the host. The home directory is shown as ~.

What you control #

What a sandbox mounts Two host directories reach the sandbox: the project you name, mounted read-write at /work/demo, and the guest home, mounted as the agent’s home. Other projects, your documents, your keychain and your SSH agent do not. Your machine Sandbox microVM, own kernel ~/code/demo the project you name ~/.brig/homes/brig-claude-code guest home ~/code/other-project ~/Documents Keychain SSH agent /work/demo read-write /root the agent’s home: settings and history claude starts in /work/demo Nothing else from your machine is mounted.
The project you name and the agent's home reach the sandbox. Nothing else does.
  • A machine for the agent. Each agent runs in a microVM with its own Linux kernel, behind a hardware boundary.
  • You choose the files. Name one project, and the agent reads and writes there. Brig mounts that project and a home for the agent's settings. Nothing else on your machine is mounted.
  • You choose the credentials. A sandbox starts with none. Deliver the ones the agent needs. Your keychain and your SSH agent stay out of reach.
  • You choose the network. Each sandbox gets a network of its own. On macOS, attach an egress policy and the agent reaches only the hosts you allow.
  • You open the ports. Publish a port, and the agent's dev server is on localhost. No other port is open.
  • Signed images. Brig checks the guest image signature before boot.
  • A clean start. brig rm removes the sandbox. Your project stays where it is.
  • Open source. Brig, hull and hvi are Apache 2.0. Runtimes gives the licence of every component.

Security model shows each boundary in detail.

What you can run #

Agent Command
Claude Code brig run claude
Codex brig run codex
Gemini CLI brig run gemini
Grok CLI brig run grok
opencode brig run opencode
Claude Desktop, on macOS brig run desktop
A plain Ubuntu shell brig run ubuntu

brig agent ls lists them on your machine. Built-in profiles prints each spec. To run your own agent or your own image, see Agent profiles and Guest images.

Minimal example #

Install Brig:

brew tap brig-sh/brig
brew trust brig-sh/brig
brew install --cask brig
curl -fsSL https://brig.sh/install | sh

Check the host. A !! line prints its fix beside it.

brig doctor

Run an agent on a project:

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

The first run pulls the guest image and the boot assets, so it is slow. Brig prints brig: image and boot assets verified. Then Claude Code asks you to log in inside the sandbox. Inside the agent, pwd prints /work/demo.

brig network publish claude 3000   # the agent's dev server, on localhost:3000
brig stop claude                   # stop the sandbox, keep its name
brig rm claude                     # stop it and remove it

brig rm also deletes the guest home that Brig created. None of these commands touches ~/code/demo.

The boundary #

brig sandbox architecture. brig run resolves the session on the host. hull drives a microVM on macOS, urunc over KVM on Linux. Both give the guest the same contract: a guest home, a project mount, per-exec credentials, and an image whose signature brig checks

brig run resolves the session on the host and boots it as a microVM. On macOS the runtime is hull. On Linux it is urunc over KVM. Both give the guest a guest home, the project mount, credentials passed per exec, and a signed image. Runtimes has the detail, and Architecture shows how hull and hvi are built.

Sessions #

A session is <agent> or <agent>@<label>. claude and claude@refactor are two independent sessions of the same agent. Each has its own sandbox and its own guest home. Sessions says what survives brig stop and brig rm.

Requirements #

Host Supported
Mac with Apple silicon, macOS 15 or newer Yes
Linux, x86-64 or arm64 Yes
Intel Mac No

Install covers macOS 14 and the per-profile limits.

Next steps #

Log an agent inThe login inside the sandbox, and Git access in the guest. Deliver a secretThe secret store, profile secret fields, and brig secret import. Restrict the networkAllow only the hosts you name, with an egress policy. Run your own agentThe profile file format. Fix a failed runOrganized by the error you saw. Ask a questionWhere to ask, and where to file a bug.

Type a command, a flag or an error message.