CI License GitHub stars

brew install joshavant/tap/clawbox
clawbox image build && clawbox up

⚠️: clawbox image build is a one-time step that downloads a large macOS base image: this can take several minutes!

Login with password clawbox then onboard your OpenClaw with:

openclaw onboard --install-daemon

That’s it! Enjoy your new crustacean. 🦞

Clawbox is a tool for deploying OpenClaw-ready macOS VMs.

Each OpenClaw instance runs in its own VM, while OpenClaw itself stays unchanged.

And, while you’re at it, you can easily provision your VM with things like Tailscale, Playwright, and more!

• Standard users: want one simple command to set up OpenClaw in its own VM.
• Developer users: want to run multiple, concurrent VMs using host-synced source/payload folders.

standard mode installs the latest official OpenClaw release in the VM.

Prerequisite (one-time requirement):

clawbox image build

Note: This is a large download and can take several minutes!

Deploy OpenClaw in a macOS VM:

clawbox up

You can also install optional services, like Tailscale, Playwright, and more:

clawbox up \
 --add-playwright-provisioning \
 --add-tailscale-provisioning \
 --add-signal-cli-provisioning

Once clawbox up completes, a Tart VM with the prepared VM will open.

Alternatively, if you'd like to SSH into your Clawbox, you can run:

ssh clawbox-1@$(clawbox ip 1)

The default password is clawbox.

See the full list in Optional Dependency Provisioning.

developer is intended for managing custom payload workflows or developing OpenClaw:

• Syncs your local OpenClaw source and payload into the VM.
• Pass those paths with --openclaw-source and --openclaw-payload.
• Uses bidirectional Mutagen sync for host<->VM source/payload changes.
• Each VM can use different checkout/payload copies for concurrent work.
• Synced checkouts are linked as the VM's openclaw command.

clawbox up --developer \
 --openclaw-source ~/Developer/openclaw-1 \
 --openclaw-payload ~/Developer/openclaw-payloads/clawbox-1

clawbox up --developer --number 1 \
 --openclaw-source ~/Developer/openclaw-1 \
 --openclaw-payload ~/Developer/openclaw-payloads/clawbox-1
clawbox up --developer --number 2 \
 --openclaw-source ~/Developer/openclaw-2 \
 --openclaw-payload ~/Developer/openclaw-payloads/clawbox-2

Note: Apple's macOS Software License Agreement permits up to two virtualized macOS instances per Apple host. Clawbox can target other VM numbers, but host virtualization limits may block additional concurrent VMs.

For source-driven dev loops in a Clawbox VM, run this inside the VM:

cd ~/Developer/openclaw
pnpm gateway:watch

Then edit files on the host in the synced source checkout (for example, ~/Developer/openclaw-1). Clawbox excludes dist from source sync so build artifacts stay VM-local while source changes still hot-reload.

Customize your VM with additional services by using these flags with up:

• Tailscale: --add-tailscale-provisioning
• Playwright + browsers: --add-playwright-provisioning
• signal-cli: --add-signal-cli-provisioning

Tailscale requires a manual, interactive approval step for permission prompts after VM creation.

To configure signal-cli with an existing configuration payload:

clawbox up --developer \
 --openclaw-source ~/Developer/openclaw-1 \
 --openclaw-payload ~/Developer/openclaw-payloads/clawbox-1 \
 --add-signal-cli-provisioning \
 --signal-cli-payload ~/.local/share/signal-cli

Rules:

• Clawbox links VM runtime ~/.local/share/signal-cli to the synced payload path and relies on Mutagen bidirectional sync.
• Single-writer locking is enforced for signal payload paths.

Details: docs/signal-cli-payload-sync.md

Recreate a VM using the original configuration options:

clawbox recreate 1

This performs down + delete + up with the same profile/flags you originally passed to up.

• Homebrew
• Node.js
• Mutagen
• OpenClaw
• Terminal.app desktop shortcut
• SSH access for clawbox-<number> (default password: clawbox)
• macOS defaults (Setup Assistant suppression, dark mode, Siri off, wallpaper, etc.)
• Tart Guest Agent (clipboard sharing support)
• Optional dependency provisioning
• ...and a lobster-toned wallpaper

• Main lifecycle: up, recreate, down, delete, status, ip
• Component workflow: create, launch, provision
• Image management: image init, image build, image rebuild

clawbox status shows the full Clawbox environment (all detected clawbox-* VMs). Use clawbox status <number> for single-VM detail.

Run clawbox --help for full command/flag docs.

• Developer and debugging guide: DEVELOPER.md
• Contributing workflow: CONTRIBUTING.md