The Dozer Sandbox manual

Dozer Sandbox runs AI coding agents in small Linux virtual machines on your Mac: each agent gets its own disk, a network that only reaches what you allow, and your project folder if you share it. A sandbox pauses in a millisecond and wakes from disk in a third of a second, with everything where you left it.

You drive it with the doz command or its dashboard in your browser (doz ui). Every page here shows both.

Reading order#

New to Dozer? Read these first, in order:

1. Getting started — install, set up, and talk to Claude in a sandbox in 15 minutes.
2. Sandboxes and their lifecycle — pause, sleep, hibernate, wake; what's kept where.
3. Terminals and sessions — attaching, the Ctrl-] menu, what the agent is doing, the clipboard, tmux.
4. What the agent can do — permissions and the network.

Then, as you need them:

• 02Installing, upgrading and uninstallinginstall with Homebrew, upgrade safely, remove Dozer
• 03Setting up(re)run onboarding in the terminal or the wizard
• 04Projectsgive a folder its own sandbox with doz_project.yaml and doz up
• 06The dashboarduse doz ui: its pages, banners, sign-in links
• 25The dashboard on your other devicesuse the dashboard from another computer, a tablet or a phone on your network (doz serve) — and behind your own HTTPS reverse proxy
• 08Images and basespick a language base, use your own Dockerfile, rebuild an out-of-date image
• 09Agents and accountsuse Claude Code or pi, add accounts, change what the agent is told
• 24Codexrun OpenAI's Codex on your ChatGPT plan (Dozer's own sign-in) or an OpenAI key — the token never enters the sandbox
• 11Signing in from a sandboxlet a tool in a sandbox sign in through your Mac's browser
• 18GitHub as youlet git and gh in a sandbox use your GitHub login — read-only or with push — without the token entering it
• 19The tools layerknow which tools Dozer puts in a sandbox for its settings (gh, the ssh client, tmux …) and check them
• 20Workspace ruleskeep the agent out of some files in your shared folder (.dozignore), or let it read but not change them (.dozreadonly)
• 21The workspace viewdozview, the small program in the sandbox every workspace goes through: why (programs keep their folder across a wake), what it costs, workspace.view, the rules it enforces, its two processes, sleep and wake, how to look inside.
• 22Prompts for your agentprompts to paste into Claude Code, Codex or Cursor on your Mac: install, set up, and three uses — a risky change, jailing an untrusted agent, a project with secrets
• 12Restore points, duplicates and templatesundo, copy a sandbox, make your own starting image
• 13Resources and disk spacesee where the disk went and free some
• 14Letting another agent drive Dozerhave the agent on your Mac run sandboxes for you
• 15Settings referencelook up any setting, its default and when it applies
• 16Security modelunderstand what protects your Mac, and what doesn't
• 17Troubleshooting and FAQfix something, or find a quick answer
• 23Audio sandboxes (EXPERIMENTAL)try a sandbox with your Mac's microphone and speakers

Conventions#

• Commands are shown as you type them: doz up. NAME is a sandbox's name; my-app is an example.
• Every command takes --json (machine-readable output), --store DIR, -v (every step) and -q (no progress). doz help COMMAND shows a command's options.
• Settings are named section.name, like sandbox.clipboard; see the Settings reference.
• Screenshots use the light theme; the dashboard follows your Mac's appearance.

This manual is checked against doz itself on every build: every command, flag and setting it names exists, and the settings reference is generated from the program.

The command-line user guide and the walkthrough cover the same ground for command-line users, more tersely.