clawops

# clawops

[![npm version](https://img.shields.io/npm/v/@clawops/cli)](https://www.npmjs.com/package/@clawops/cli)
[![npm downloads](https://img.shields.io/npm/dm/@clawops/cli)](https://www.npmjs.com/package/@clawops/cli)

MCP-native infrastructure ops for OpenClaw — with read-only mode, destructive-action confirmation, and audit logs built in.

**clawops** is a CLI and [MCP](https://modelcontextprotocol.io/) server for deploying and operating
self-hosted [OpenClaw](https://github.com/openclaw/openclaw) instances. Provision on AWS, GCP,
Azure, or any Linux VM — then manage day-to-day operations from the terminal, or let Claude Code
and Cursor drive them through typed MCP tools with explicit safety controls.

---

## What's new in 2.0.1

A patch release, and a large one: in 2.0.0 no cloud deploy succeeded by any path. Every item
below is a fix or an addition in 2.0.1. The reasoning behind each one is in its commit message,
and the decisions that came out of them are in [`docs/decisions/`](docs/decisions/).

### Deploying to a cloud

- `clawops plan` → `clawops apply` provisions a cloud stack and deploys OpenClaw onto it.
- `clawops up` deploys to AWS, GCP and Azure, running the same path as `plan` → `apply`.
- clawops installs the Pulumi CLI it needs into `~/.clawops/.pulumi-cli`, or uses a compatible
  one already on `$PATH` ([ADR 0010](docs/decisions/0010-pulumi-cli-bootstrap.md)).
- clawops creates and stores the passphrase its state backend requires
  ([ADR 0011](docs/decisions/0011-state-passphrase.md)).
- `clawops plan` takes `--ssh-cidr`, `--gateway-cidr` and `--publish-gateway`, and `apply`
  passes them to the cloud firewall. `auto` resolves this machine's address.
- `clawops plan` stops, and names the cause, when it cannot open the state backend.
- `--instance-type` takes a clawops alias (`micro`–`gpu`) or a machine type your cloud names
  itself, and the plan records the concrete type.
- Deploys pin the account they were planned against: `gcp:project` on GCP,
  `azure-native:subscriptionId` on Azure.

### Checking the account before you spend

- `clawops doctor --provider <cloud>` checks one cloud's credentials and account setup, with or
  without a stack. `--instance-type` points the size check at the size you are deploying.
- **AWS** — the account the credentials resolve to, the state bucket, and whether the instance
  type is offered in the region.
- **GCP** — the project, the APIs a deploy needs, and the state bucket.
- **Azure** — the subscription, the resource providers, the VM size, and the azblob credentials
  Pulumi authenticates with.
- `clawops setup` runs the same checks and offers to fix what it safely can — enabling an API,
  creating a state bucket with versioning on and public access blocked — naming the change
  before making it.
- A check clawops could not perform reports as a warning naming the error, rather than as a
  pass or a failure.
- Azure accepts your `az login`; a service principal is no longer required.

### Naming, config and setup

- clawops names the state backend after the account it is deploying into, instead of asking you
  for a name or writing a placeholder
  ([ADR 0012](docs/decisions/0012-state-bucket-naming.md)).
- A name you type instead is checked against the rules of the cloud that has to accept it.
- `clawops init` keeps the stacks already in your config.
- `clawops init` generates an SSH key that clawops can read. If you ran `init` before this
  release, `clawops doctor` will tell you whether yours is usable.
- `gcloud config set project` is honoured.
- The setup wizard writes model configuration that OpenClaw accepts, and installs the plugin
  your chosen provider needs.
- Amazon Bedrock works: the right transport, and an inference profile resolved against your
  deployment region and recorded in the plan. Needs `bedrock:ListInferenceProfiles`.

### While a deploy is running

- `apply` waits for SSH, then waits for the gateway to answer, before reporting success.
- `apply` reports progress as it goes instead of going quiet for minutes.
- A deploy that times out prints what the host was doing, from its bootstrap log.
- A host still installing Docker is treated as still booting rather than as a failed deploy.

### Day-two commands

- `clawops logs` reads from the gateway on AWS.
- `doctor --stack`, `ssh`, `logs`, `gateway`, `config` and `agents` work against a freshly
  deployed stack.
- `clawops doctor` validates cloud credentials.
- clawops tells a refused Docker socket from a missing container, and says which it found.
- `clawops destroy` forgets the instance's host key, so redeploying onto an address the cloud
  has recycled no longer fails verification.

### Documentation

- The GCP guide names the credential source clawops actually reads, and describes 2.0
  firewall behaviour.
- The smoke-test plan covers 2.0, and `pnpm test:cloud aws|gcp|azure` runs it against a real
  deployment and destroys it afterwards.

## What's new in 2.0

clawops 2.x targets **OpenClaw >= 2026.9.2**. The 1.x line continues for OpenClaw
`<= 2026.7.1-2` under the `legacy` dist-tag until **2027-03-31**:

```bash
npm install -g @clawops/cli            # 2.x
npm install -g @clawops/cli@legacy     # 1.x maintenance
```

Pin the tag in CI — `latest` moves to 2.x, so an unpinned pipeline will change lines.
[`CHANGELOG.md`](CHANGELOG.md) carries the full history; this section covers what changed
about *how clawops behaves*.

### Your deployment keeps its state

OpenClaw 2.0 stores sessions, transcripts and credentials in SQLite. clawops mounted no
state at all, so **every restart destroyed them** — and a restart is what `gateway restart`,
`gateway update` and `config set` all do.

One host directory (`/var/lib/clawops/openclaw`) is now bind-mounted at OpenClaw's own
default location, holding the config, the database and any provider plugins. Existing
deployments migrate on the next `up`/`apply`.

### `clawops up` / `clawops apply`

```mermaid
flowchart TD
    A["clawops plan"] --> B{"config valid<br/>against OpenClaw schema?"}
    B -- no --> B1["refuse — plan is still<br/>a file you can edit"]
    B -- yes --> C["clawops apply"]
    C --> D{"OpenClaw version<br/>in supported range?"}
    D -- no --> D1["refuse — names<br/>@clawops/cli@legacy"]
    D -- yes --> E["provision host"]
    E --> F["state dir, owned 1000:1000<br/>migrate any pre-2.0 config"]
    F --> G["write config<br/>validated before writing"]
    G --> H["install provider plugins<br/>while egress exists"]
    H --> I["start gateway"]
    I --> J{"/startupz says started?"}
    J -- no --> J1["fail with the reason"]
    J -- yes --> K{"configured providers<br/>all loaded?"}
    K -- no --> K1["warn — healthy gateway,<br/>missing model backend"]
    K -- yes --> L["done"]
```

Three of those steps are new, and each exists because the old flow could report success
while something was wrong: the config was never validated before being written, provider
plugins were left to be fetched at boot (or silently missing on a deny-all host), and
"started" was inferred from `docker run` exiting 0.

### `clawops gateway update`

Previously: pull, run, report success. `docker run` exiting 0 means the container was
*created* — and the container it replaced is already gone.

```mermaid
flowchart TD
    A["clawops gateway update X"] --> B{"X in supported range?"}
    B -- no --> B1["refuse before pulling"]
    B -- yes --> C["docker pull X"]
    C --> D["snapshot state database"]
    D -- cannot snapshot --> D1["refuse — no rollback point"]
    D --> E{"target release understands<br/>this schema?"}
    E -- no --> E1["refuse — downgrade across<br/>a schema boundary"]
    E -- yes --> F["swap container"]
    F --> G{"/startupz says started?"}
    G -- yes --> H["done"]
    G -- no --> I["one-shot doctor --fix<br/>in a throwaway container"]
    I --> J["re-run, re-gate"]
    J -- started --> K["done — reported as repaired"]
    J -- still not --> L["roll back to previous image"]
    L -- started --> M["rolled back, reason reported"]
    L -- still not --> N["failed — snapshot path named"]
```

The snapshot is not only a rollback point: `database preflight` refuses a live database
because the schema version sits in the WAL until checkpointed, so the consolidated snapshot
is what makes the compatibility check possible at all.

### `clawops gateway restart`

A restart changes neither the deployed version nor who can reach the gateway. Both are read
back from the running container rather than guessed:

```mermaid
flowchart LR
    A["gateway restart"] --> B["read current image"]
    B -- no container --> B1["refuse — nothing to reuse.<br/>latest and stable point at 2.0"]
    B --> C["read current publish scope"]
    C --> D["recreate with the same<br/>version and reachability"]
    D --> E{"/startupz says started?"}
    E -- no --> E1["fail with the reason"]
    E -- yes --> F["done"]
```

### Migrating an existing 1.x deployment

```mermaid
flowchart TD
    A["clawops migrate"] --> B{"1.x container running?"}
    B -- no --> B1["nothing to rescue — state was<br/>already lost to an earlier restart"]
    B -- yes --> C["verified backup, inside the running container"]
    C -- "backup fails" --> C1["refused — nothing touched"]
    C --> D["extract state from the RUNNING container"]
    D --> E["chown 1000:1000"]
    E --> F["stop and remove 1.x"]
    F --> G["synthesise a valid 2.0 config"]
    G --> H["start 2.0 with the state directory"]
    H --> I{"/startupz started?"}
    I -- "no — schema still migrating" --> J["restart once"]
    J --> K{"started?"}
    K -- no --> K1["failed — points at the backup"]
    K --> L["report"]
    I -- yes --> L
    L --> M["what carried over,<br/>device identity, config to review"]
```

Two things about that shape are not obvious, and both came from running a real migration:

**State is extracted from the *running* container.** All 1.x state lived inside it — clawops
mounted none — so stopping first destroys