clawctl

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.

Getting Started · Headless Mode · Config Reference · Troubleshooting

---

Install

curl -fsSL https://raw.githubusercontent.com/TimBeyer/clawctl/main/install.sh | bash

Requires macOS on Apple Silicon (M1–M4) with Homebrew. Lima is installed automatically.

Quickstart

clawctl create

In 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

For automated setups, pass a JSON config file and skip the prompts — see Headless Mode.

Features

• 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 and env:// 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

Commands

Note

Terminology: A clawctl instance is a Lima VM running an OpenClaw gateway. The gateway hosts one or more agents. clawctl manages the instance lifecycle; OpenClaw manages the agents inside it.

Command	Description
clawctl create	Interactive wizard
clawctl create --config <path>	Config-driven with TUI progress
clawctl create --config <path> --plain	Plain log output (CI/automation)
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
clawctl completions <shell>	Generate shell completion script (bash or zsh)

Instance commands accept an optional name, a -i/--instance flag, or resolve automatically from context (CLAWCTL_INSTANCE env var, .clawctl file, or global default via clawctl use).

Tip

No need to shell in for routine operations — clawctl oc runs any openclaw subcommand inside the VM: clawctl oc doctor, clawctl oc config get gateway.name, etc.

Shell completions

Enable tab completion for commands, options, instance names, and openclaw subcommands:

# Bash — add to ~/.bashrc:
eval "$(clawctl completions bash)"

# Zsh — add to ~/.zshrc:
eval "$(clawctl completions zsh)"

openclaw subcommand completions (including deep completion like oc config set <TAB>) are cached from the VM and refreshed automatically. See Shell Completions for details.

Documentation

• 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
• Shell Completions — tab completion setup and openclaw cache mechanics
• Troubleshooting — common issues and fixes

Contributing

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 check

To install to a custom directory, set INSTALL_DIR:

INSTALL_DIR=~/.local/bin curl -fsSL https://raw.githubusercontent.com/TimBeyer/clawctl/main/install.sh | bash

See 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 create

Your gateway will be running in its own isolated VM in minutes.