Run OpenClaw gateways in isolated VMs — managed entirely from your Mac.
You never touch the VM. Config lives on your host, git-tracked and reproducible.
clawctl gives each OpenClaw gateway its own isolated Ubuntu VM via Lima, provisions it with everything OpenClaw needs, and manages the full lifecycle from your Mac. You never shell in or piece together scripts — just answer a few questions (or hand it a config file) and the gateway is running. Config and data are mounted into a project directory on your host, so they're editable, git-trackable, and safe from VM rebuilds.
Terminology: A clawctl instance is a Lima VM running an OpenClaw gateway. The gateway hosts one or more agents — each with its own workspace, sessions, and tools. clawctl manages the instance lifecycle; OpenClaw manages the agents inside it.
curl -fsSL https://raw.githubusercontent.com/TimBeyer/clawctl/main/install.sh | bashTo update an existing installation, run the same command again.
Requires macOS on Apple Silicon (M1/M2/M3/M4) with Homebrew installed. Lima is installed automatically if not already present.
# Interactive wizard — answers a few questions, does everything else
clawctl create
# Headless — config-file-driven, no prompts, great for CI/CD
clawctl create --config config.jsonIn about five minutes, the wizard gives you:
- A running OpenClaw gateway with a dashboard at
http://localhost:18789 - An isolated Ubuntu 24.04 VM with Node.js, Tailscale, and the 1Password CLI pre-installed
- A project directory on your Mac with git-tracked config and persistent data that survives VM rebuilds
You just answer a few questions. clawctl handles prerequisites, VM creation, provisioning, and — optionally — credential setup and OpenClaw onboarding.
- Fully isolated — each gateway runs in its own Ubuntu VM; nothing installed on your Mac
- Zero VM wrangling — interactive wizard or headless config file, no manual provisioning
- Git-friendly — config and data live in your project directory, not buried in a VM
- Reproducible — delete the VM, recreate it, pick up right where you left off
- Secret management — 1Password
op://references andenv://variables; zero plaintext secrets in config - Remote access — optional Tailscale integration for accessing your gateway from anywhere
- 15+ AI providers — Anthropic, OpenAI, Gemini, Mistral, and more out of the box
- Run multiple gateways — each instance gets its own isolated VM; spin up as many as you need
- CI/CD ready — headless mode for fully automated provisioning
| Command | Description |
|---|---|
clawctl create |
Interactive wizard |
clawctl create --config <path> |
Headless mode (config-file-driven) |
clawctl list |
List all instances with live status |
clawctl status [name] |
Detailed info for one instance |
clawctl start [name] |
Start a stopped instance |
clawctl stop [name] |
Stop a running instance |
clawctl restart [name] |
Stop + start + health checks |
clawctl delete [name] [--purge] |
Delete VM; --purge also removes project dir |
clawctl shell [name] |
Interactive shell into the VM |
clawctl shell [name] -- <cmd...> |
Run a command in the VM |
clawctl openclaw <subcommand...> |
Run an openclaw command in the VM (alias: oc) |
clawctl use [name] [--global] |
Set or show the current instance context |
clawctl register <name> --project <path> |
Register an existing (pre-registry) instance |
All instance commands (status, start, stop, restart, delete, shell,
openclaw) accept an optional positional name, a -i/--instance flag, or
resolve the instance automatically via context. Run clawctl --help for
details.
You don't have to type the instance name every time. clawctl resolves the target instance in this order:
--instance/-iflag —clawctl status -i my-agentCLAWCTL_INSTANCEenv var —export CLAWCTL_INSTANCE=my-agent.clawctlfile — walks up from your current directory (like.nvmrc)- Global context —
~/.config/clawctl/context.json
Set context with clawctl use:
clawctl use my-agent # write .clawctl in current directory
clawctl use my-agent --global # set global default
clawctl use # show current context and its sourceNo need to shell in for routine operations — clawctl openclaw (or oc for
short) runs any openclaw subcommand inside the VM:
clawctl oc doctor # health check
clawctl oc config get gateway.name
clawctl oc daemon status
clawctl oc telegram listFor arbitrary commands, use clawctl shell --:
clawctl shell -- whoami
clawctl shell -- systemctl --user status openclaw-gatewayclawctl isn't just an installer — it's how you manage your gateways after setup too.
# Set your default instance once
clawctl use my-agent
# See what's running
clawctl list
# Quick health check — no need to shell in
clawctl oc doctor
# Restart one that's acting up
clawctl restart
# Spin up a second gateway for a different project
clawctl create
# Tear it down when you're done (keeps your project dir by default)
clawctl delete my-agentInstances are tracked in ~/.config/clawctl/instances.json and registered
automatically on create, or manually via clawctl register. Run as many
gateways as your hardware allows — each gets its own isolated VM, project
directory, and config.
- Getting Started — guided walkthrough for first-time users
- Headless Mode — config-file-driven provisioning for CI and scripted setups
- Config Reference — full schema for headless config files
- 1Password Setup — service accounts and
op://secret references - Tailscale Setup — auth keys, ACLs, remote dashboard access
- Snapshots and Rebuilds — cloning VMs, data persistence, full rebuilds
- Project Directory — what the CLI creates and how to customize it
- Troubleshooting — common issues and fixes
bun bin/cli.tsx create # run the wizard
bun bin/cli.tsx create --config examples/config.json # headless mode
bun build ./bin/cli.tsx --compile --outfile dist/clawctl # build binary
bun test # unit tests
bun run lint # ESLint
bun run format:check # Prettier checkTo install to a custom directory, set INSTALL_DIR:
INSTALL_DIR=~/.local/bin curl -fsSL https://raw.githubusercontent.com/TimBeyer/clawctl/main/install.sh | bashSee Architecture, CLI Wizard Flow, VM Provisioning, and Testing for internals.
Ready to go?
curl -fsSL https://raw.githubusercontent.com/TimBeyer/clawctl/main/install.sh | bash
clawctl createYour gateway will be running in its own isolated VM in minutes.