https://github.com/TimBeyer/clawctl
Run OpenClaw gateways in isolated VMs
https://github.com/TimBeyer/clawctl
clawbot clawctl cli openclaw openclaw-installer openclaw-setup openclaw-vm
Last synced: about 2 months ago
JSON representation
Run OpenClaw gateways in isolated VMs
- Host: GitHub
- URL: https://github.com/TimBeyer/clawctl
- Owner: TimBeyer
- Created: 2026-03-04T22:36:03.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-05-13T23:18:32.000Z (about 2 months ago)
- Last Synced: 2026-05-13T23:34:13.444Z (about 2 months ago)
- Topics: clawbot, clawctl, cli, openclaw, openclaw-installer, openclaw-setup, openclaw-vm
- Language: TypeScript
- Homepage: https://timbeyer.github.io/clawctl/
- Size: 8.85 MB
- Stars: 16
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
Awesome Lists containing this project
README
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
```bash
curl -fsSL https://raw.githubusercontent.com/TimBeyer/clawctl/main/install.sh | bash
```
Requires macOS on Apple Silicon (M1–M4) with [Homebrew](https://brew.sh). Lima is installed automatically.
## Quickstart
```bash
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](docs/headless-mode.md).
## 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](docs/headless-mode.md) 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 ` | Config-driven with TUI progress |
| `clawctl create --config --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] -- ` | Run a command in the VM |
| `clawctl openclaw ` | Run an `openclaw` command in the VM (alias: `oc`) |
| `clawctl mount list [name]` | List all mounts for an instance |
| `clawctl mount add ` | Add a host directory mount (`--writable` for rw) |
| `clawctl mount remove ` | Remove a user-added mount |
| `clawctl use [name] [--global]` | Set or show the current instance context |
| `clawctl register --project ` | Register an existing (pre-registry) instance |
| `clawctl completions ` | 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
# 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
`) are cached from the VM and refreshed automatically. See [Shell
Completions](docs/shell-completions.md) for details.
## Documentation
- [Getting Started](docs/getting-started.md) — guided walkthrough for first-time users
- [Headless Mode](docs/headless-mode.md) — config-file-driven provisioning for CI and scripted setups
- [Config Reference](docs/config-reference.md) — full schema for headless config files
- [1Password Setup](docs/1password-setup.md) — service accounts and `op://` secret references
- [Tailscale Setup](docs/tailscale-setup.md) — auth keys, ACLs, remote dashboard access
- [Snapshots and Rebuilds](docs/snapshots-and-rebuilds.md) — cloning VMs, data persistence, full rebuilds
- [Project Directory](docs/project-directory.md) — what the CLI creates and how to customize it
- [Shell Completions](docs/shell-completions.md) — tab completion setup and openclaw cache mechanics
- [Troubleshooting](docs/troubleshooting.md) — common issues and fixes
## Contributing
```bash
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`:
```bash
INSTALL_DIR=~/.local/bin curl -fsSL https://raw.githubusercontent.com/TimBeyer/clawctl/main/install.sh | bash
```
See [Architecture](docs/architecture.md), [CLI Wizard Flow](docs/cli-wizard-flow.md),
[VM Provisioning](docs/vm-provisioning.md), and [Testing](docs/testing.md) for internals.
---
**Ready to go?**
```bash
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.