Provisions and manages self-hosted OpenClaw instances on AWS, GCP, Azure, or local VMs using typed MCP tools and safe infrastructure operations.
Also known as dfridkin/clawops, @clawops/cli
- Stars
- 6
- Tools
- 30
- Downloads, 30 days
- 1,625
- Latest version
- 2.5.0
- Last commit
- Nov 7, 2026
- License
- MPL-2.0
What is clawops MCP?
clawops provisions and manages self-hosted OpenClaw instances on AWS, GCP, Azure, or local VMs using typed MCP tools and safe infrastructure operations. It exposes 30 tools, such as clawops_status, clawops_doctor, clawops_logs_tail.
Summary generated from the project's README
About clawops MCP server
clawops provides a specialized interface for deploying and managing self-hosted OpenClaw instances across various environments. It supports provisioning on AWS, GCP, Azure, or local Linux and macOS virtual machines. The tool uses the Pulumi Automation API to handle infrastructure setup, automatically installing the necessary CLI components on the first use. It is designed for developers and AI enthusiasts who want to run their own AI assistants without relying on managed SaaS platforms or complex Kubernetes clusters.
This server functions as an MCP-native infrastructure operations tool, allowing AI clients like Claude Code, Cursor, and Windsurf to interact with your deployment. It includes built-in safety features such as a read-only mode, audit logs, and mandatory confirmation for destructive actions. Users must provide existing cloud credentials through environment variables like AWS_PROFILE, as the server never stores sensitive cloud keys. The system follows a plan, review, and apply workflow to ensure cloud deployments remain predictable and controlled.
What you can do with it
- 1Automated infrastructure provisioningAn AI agent can deploy a new OpenClaw instance on a specific cloud provider using a guided setup process.
- 2Safe infrastructure monitoringA developer can ask an AI to check the current status and logs of a running OpenClaw stack.
- 3Remote configuration managementYou can instruct an AI client to update specific settings within your OpenClaw configuration.
- 4Secure cloud deployment workflowsUse an AI to generate and review a deployment plan before applying changes to your cloud environment.
Written from the project's README. Every use case is checked against a quote from it.
How to install clawops MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall clawops MCP in Claude Code
$ claude mcp add clawops -- npx -y @clawops/cli mcp serveInstall clawops MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"clawops": {
"command": "npx",
"args": [
"-y",
"@clawops/cli",
"mcp",
"serve"
]
}
}
}Install clawops MCP in VS Code
.vscode/mcp.json
{
"servers": {
"clawops": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@clawops/cli",
"mcp",
"serve"
]
}
}
}Install clawops MCP in VS Code CLI
$ code --add-mcp '{"name":"clawops","type":"stdio","command":"npx","args":["-y","@clawops/cli","mcp","serve"]}'Install clawops MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"clawops": {
"command": "npx",
"args": [
"-y",
"@clawops/cli",
"mcp",
"serve"
]
}
}
}Install clawops MCP in Codex
$ codex mcp add clawops -- npx -y @clawops/cli mcp serveInstall clawops MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.clawops] command = "npx" args = ["-y", "@clawops/cli", "mcp", "serve"]
Install clawops MCP in Gemini CLI
$ gemini mcp add -s user clawops npx -- -y @clawops/cli mcp serveInstall clawops MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"clawops": {
"command": "npx",
"args": [
"-y",
"@clawops/cli",
"mcp",
"serve"
]
}
}
}Started by HostedMCP on 16 Nov 2026
We ran this command for @clawops/cli 2.5.0 in an isolated container with no network and no keys. It answered and listed 30 tools.
clawops MCP tools 30
Read from the server with tools/listclawops_statusRead-onlyGet what is deployed for a clawops-managed stack: public IP, gateway URL, SSH user, or that nothing is deployed yet. Reads stack outputs, and asks the host only for requests its host agent left for the operator (pendingHandoffs): each is a clawops command to show the user as it is. A request clears when that command is run, or after 7 days. Use when: the user asks what exists for a stack, where to reach it, or whether its agent is waiting on them. Do NOT use when: the user asks whether the gateway is actually WORKING — that needs the host, so use clawops_doctor. Also not for live logs (use clawops_logs_tail) or config values (use clawops_config_get).
clawops_doctorRead-onlyRun clawops's diagnostics and return the report: Node and Pulumi runtime, config, SSH key and known_hosts, cloud credentials per configured provider, and the supported OpenClaw range. With stackName, also contacts the host for container state, the deployed OpenClaw version, a real gateway health probe, whether the port is published to the internet, disk usage on the state directory, log rotation, and hardening drift. Use when: something is not working and you do not yet know what; before any deploy, upgrade or migration; or to find out which OpenClaw version a gateway is actually running. Do NOT use when: you already know the problem and want to fix it. This tool only reports — it changes nothing, and never runs `openclaw doctor --fix`. To move a gateway to another version, use clawops_gateway_update after clawops_backup_create. Every check carries a status: fail (something is wrong that clawops can name), warn (worth knowing, not broken), info (did not apply). `ok` is false only when something failed — a fresh machine with no stacks is full of warnings and healthy.
clawops_logs_tailRead-onlyTail recent gateway logs from a clawops-managed instance. Use when: the user wants to investigate recent activity or errors, or asks "what's been happening" on the gateway. Do NOT use when: the user wants real-time streaming logs (those are not well-suited to tool calls; suggest the user run `clawops logs -f` directly in their terminal). Do NOT use for instance-level system logs: no tool runs arbitrary remote commands, so tell the user to run `clawops ssh --command 'journalctl ...'` themselves.
clawops_monitorRead-onlyTake a live snapshot of a running clawops stack: gateway health, container status, resource usage (CPU, memory, disk), and recent log lines. Use when: the user wants to know if the gateway is running, how much memory or CPU it is using, what recent log activity looks like, or wants a quick health overview richer than clawops_status. Do NOT use when: the user wants real-time streaming logs (use clawops_logs_tail or suggest `clawops logs -f`). Do NOT use for configuration queries (use clawops_config_get).
clawops_config_getRead-onlyRead a configuration value from the remote OpenClaw gateway. Use when: the user wants to inspect current OpenClaw config (e.g., which model provider is active, which channels are enabled). Do NOT use when: the user wants to change the config — use clawops_config_set instead.
clawops_agents_listRead-onlyList agents currently registered on the remote OpenClaw gateway. Use when: the user wants to see which agents are running, debug agent routing, or count active workspaces. Do NOT use when: the user wants one agent's activity — that is clawops_agents_logs.
clawops_agents_logsRead-onlyOne agent's recent activity, read from the gateway's audit log, newest last. Paginated: pass the returned cursor to continue. Use when: the user asks what a specific agent did, or why it behaved as it did. Do NOT use when: the user wants the gateway's own log stream — that is clawops_logs_tail. Do NOT use to find agent names — that is clawops_agents_list.
clawops_gateway_statusRead-onlyWhether the OpenClaw gateway container is running, when it started, and which image it runs, as docker reports it on the host. Use when: the user asks whether the gateway is up or which OpenClaw version is deployed. Do NOT use when: the user wants a full health check — clawops_doctor probes the gateway itself rather than the container. Do NOT use to change anything; this only reads.
clawops_secret_listRead-onlyList the secrets clawops stores locally, by name and status. Never returns a value. Use when: the user asks which secrets are set, or before a deploy that references one. Do NOT use when: the user wants to set or rotate a secret. No tool does that, because the value would pass through the conversation (R6): ask the user to run `clawops secret set <NAME>` or `clawops secret rotate <NAME>` in a terminal.
clawops_secret_auditRead-onlyReport secrets that stacks reference but clawops does not have, and `$secret:` references that cannot be resolved. Never returns a value. Use when: a deploy or config change fails on a missing secret, or before applying a plan whose config references secrets. Do NOT use when: the user wants to set the missing secret — ask them to run `clawops secret set <NAME>` in a terminal; no tool takes a secret value (R6).
clawops_upActionProvision and deploy a clawops stack. Idempotent — re-running with no spec change produces no diff. Long-running (median 3min, p99 8min) so emits progress notifications per R12. Use when: the user explicitly asks to deploy, provision, create, or "spin up" a stack. Always after the user has reviewed a plan (clawops_plan first when in doubt). Do NOT use when: the user has not yet generated a plan and is in exploratory/discovery mode — use clawops_plan first. Do NOT use for an existing stack you only need to update; refresh first.
clawops_destroyActionDestroy a clawops stack. Removes ALL provisioned resources. Triggers elicitation confirmation showing the resource diff before execution (R19). Cannot be undone. Use when: the user explicitly asks to destroy, tear down, delete, or remove a stack. Always confirm the stack name. Do NOT use when: the user wants to stop the gateway temporarily — that is not a destroy, and no tool stops a gateway; clawops_gateway_restart restarts it. Do NOT use when in doubt about which stack; list first with clawops_stacks_list.
| clawops_status | Get what is deployed for a clawops-managed stack: public IP, gateway URL, SSH user, or that nothing is deployed yet. Reads stack outputs, and asks the host only for requests its host agent left for the operator (pendingHandoffs): each is a clawops command to show the user as it is. A request clears when that command is run, or after 7 days. Use when: the user asks what exists for a stack, where to reach it, or whether its agent is waiting on them. Do NOT use when: the user asks whether the gateway is actually WORKING — that needs the host, so use clawops_doctor. Also not for live logs (use clawops_logs_tail) or config values (use clawops_config_get). | Read-only |
| clawops_doctor | Run clawops's diagnostics and return the report: Node and Pulumi runtime, config, SSH key and known_hosts, cloud credentials per configured provider, and the supported OpenClaw range. With stackName, also contacts the host for container state, the deployed OpenClaw version, a real gateway health probe, whether the port is published to the internet, disk usage on the state directory, log rotation, and hardening drift. Use when: something is not working and you do not yet know what; before any deploy, upgrade or migration; or to find out which OpenClaw version a gateway is actually running. Do NOT use when: you already know the problem and want to fix it. This tool only reports — it changes nothing, and never runs `openclaw doctor --fix`. To move a gateway to another version, use clawops_gateway_update after clawops_backup_create. Every check carries a status: fail (something is wrong that clawops can name), warn (worth knowing, not broken), info (did not apply). `ok` is false only when something failed — a fresh machine with no stacks is full of warnings and healthy. | Read-only |
| clawops_logs_tail | Tail recent gateway logs from a clawops-managed instance. Use when: the user wants to investigate recent activity or errors, or asks "what's been happening" on the gateway. Do NOT use when: the user wants real-time streaming logs (those are not well-suited to tool calls; suggest the user run `clawops logs -f` directly in their terminal). Do NOT use for instance-level system logs: no tool runs arbitrary remote commands, so tell the user to run `clawops ssh --command 'journalctl ...'` themselves. | Read-only |
| clawops_monitor | Take a live snapshot of a running clawops stack: gateway health, container status, resource usage (CPU, memory, disk), and recent log lines. Use when: the user wants to know if the gateway is running, how much memory or CPU it is using, what recent log activity looks like, or wants a quick health overview richer than clawops_status. Do NOT use when: the user wants real-time streaming logs (use clawops_logs_tail or suggest `clawops logs -f`). Do NOT use for configuration queries (use clawops_config_get). | Read-only |
| clawops_config_get | Read a configuration value from the remote OpenClaw gateway. Use when: the user wants to inspect current OpenClaw config (e.g., which model provider is active, which channels are enabled). Do NOT use when: the user wants to change the config — use clawops_config_set instead. | Read-only |
| clawops_agents_list | List agents currently registered on the remote OpenClaw gateway. Use when: the user wants to see which agents are running, debug agent routing, or count active workspaces. Do NOT use when: the user wants one agent's activity — that is clawops_agents_logs. | Read-only |
| clawops_agents_logs | One agent's recent activity, read from the gateway's audit log, newest last. Paginated: pass the returned cursor to continue. Use when: the user asks what a specific agent did, or why it behaved as it did. Do NOT use when: the user wants the gateway's own log stream — that is clawops_logs_tail. Do NOT use to find agent names — that is clawops_agents_list. | Read-only |
| clawops_gateway_status | Whether the OpenClaw gateway container is running, when it started, and which image it runs, as docker reports it on the host. Use when: the user asks whether the gateway is up or which OpenClaw version is deployed. Do NOT use when: the user wants a full health check — clawops_doctor probes the gateway itself rather than the container. Do NOT use to change anything; this only reads. | Read-only |
| clawops_secret_list | List the secrets clawops stores locally, by name and status. Never returns a value. Use when: the user asks which secrets are set, or before a deploy that references one. Do NOT use when: the user wants to set or rotate a secret. No tool does that, because the value would pass through the conversation (R6): ask the user to run `clawops secret set <NAME>` or `clawops secret rotate <NAME>` in a terminal. | Read-only |
| clawops_secret_audit | Report secrets that stacks reference but clawops does not have, and `$secret:` references that cannot be resolved. Never returns a value. Use when: a deploy or config change fails on a missing secret, or before applying a plan whose config references secrets. Do NOT use when: the user wants to set the missing secret — ask them to run `clawops secret set <NAME>` in a terminal; no tool takes a secret value (R6). | Read-only |
| clawops_up | Provision and deploy a clawops stack. Idempotent — re-running with no spec change produces no diff. Long-running (median 3min, p99 8min) so emits progress notifications per R12. Use when: the user explicitly asks to deploy, provision, create, or "spin up" a stack. Always after the user has reviewed a plan (clawops_plan first when in doubt). Do NOT use when: the user has not yet generated a plan and is in exploratory/discovery mode — use clawops_plan first. Do NOT use for an existing stack you only need to update; refresh first. | Action |
| clawops_destroy | Destroy a clawops stack. Removes ALL provisioned resources. Triggers elicitation confirmation showing the resource diff before execution (R19). Cannot be undone. Use when: the user explicitly asks to destroy, tear down, delete, or remove a stack. Always confirm the stack name. Do NOT use when: the user wants to stop the gateway temporarily — that is not a destroy, and no tool stops a gateway; clawops_gateway_restart restarts it. Do NOT use when in doubt about which stack; list first with clawops_stacks_list. | Action |
Show all 30 toolsShow fewer tools
clawops_applyActionApply a previously-generated Maker plan (deploy-plan.schema.json). Deterministic — the plan describes exactly what will be created. Use when: the user has a plan file path and wants to apply it. This is the agent-friendly path for any deploy/destroy operation. Do NOT use when: there's no plan file — generate one first with clawops_plan.
clawops_planRead-onlyGenerate a Maker deploy plan (does NOT apply). Plan is JSON conforming to deploy-plan.schema.json — review before applying. Use when: the user wants to see what would be created before committing, or you (the agent) need a reviewable artifact for the user to approve. Do NOT use when: the user has explicitly asked to deploy and you already have their approval — go directly to clawops_up.
clawops_config_setActionSet a configuration value on the remote OpenClaw gateway. Optionally restarts the gateway after. Use when: the user wants to change OpenClaw configuration (model provider, channel auth, gateway port). Do NOT use when: the user is reading config — use clawops_config_get. Do NOT bulk-edit; one key at a time so changes are auditable (R21).
clawops_config_unsetActionRemove a configuration key from the remote OpenClaw gateway config, reverting it to the OpenClaw default. Use when: the user wants to delete a config key entirely (e.g., remove a channel, clear an override). Do NOT use when: the user wants to set the key to a new value — use clawops_config_set instead.
clawops_config_validateRead-onlyValidate the remote OpenClaw gateway config against the known schema. Checks for structural errors (wrong types, unknown top-level keys) that would cause OpenClaw to fail on startup. Use when: the user wants to verify config before restarting the gateway, or after editing openclaw.json manually. Do NOT use when: the user wants to change config — use clawops_config_set.
clawops_gateway_restartActionRestart the OpenClaw gateway daemon on the remote instance. Use when: a gateway-wide config change requires reload, or the gateway is reported as unresponsive. Note: OpenClaw 2.0 removed per-agent restart; `gateway restart` is the only restart it offers, and it affects every agent on the host. Brief downtime (~10s).
clawops_gateway_updateActionMove the gateway to a different OpenClaw version: pull the image and restart the gateway on it. Every agent on the host restarts with it. Use when: the user asks to upgrade or downgrade OpenClaw on a running stack, naming a version. Do NOT use when: the user has not named a concrete version — moving tags such as `latest` are refused, as the CLI refuses them. Do NOT use without a backup the user can return to: suggest clawops_backup_create first.
clawops_backup_createActionTake a backup of the gateway's state (config, database, sessions, transcripts and installed plugins) and download it to a local archive. Live state is not changed. Use when: the user asks for a backup, and before anything that replaces state: a version update, a migration, a restore, or a plan that replaces the instance. Do NOT use when: the user wants to back up cloud infrastructure — Pulumi state and plans cover that, not this.
clawops_backup_restoreActionVerify a backup archive and expand it on the host beside the live state, never over it. With activate: true, also put it into service: stop the gateway, swap the restored state in (keeping the state it replaces), restart, and roll back if the gateway does not answer. Use when: the user asks to restore or recover from a backup, naming the archive. Do NOT use when: the gateway is merely unhealthy — clawops_workflow_recover diagnoses that without discarding state. Restoring is time travel: everything since the backup is lost, and channel credentials may need relinking.
clawops_migrateActionMove a deployment from OpenClaw 1.x onto the 2.0 runtime contract: state ownership, config, and the gateway's run command, in the order a real migration showed works. Use when: a stack still runs OpenClaw 1.x and the user wants it on 2.x. clawops_doctor and clawops_gateway_status say which line a stack runs. Do NOT use when: the stack is already on 2.x — use clawops_gateway_update to change versions within 2.x. Take a backup first with clawops_backup_create.
clawops_secret_deleteActionDelete a locally stored secret by name. Warns when a stack still references it. Use when: the user asks to remove a secret they no longer use. Do NOT use when: the user wants to replace a value — ask them to run `clawops secret rotate <NAME>`; no tool takes a secret value (R6).
clawops_initActionRegister a stack and write ~/.clawops/config.json: the provider, the state backend, the region, and an SSH key pair generated if one is not already there. Nothing is provisioned and nothing is charged; this only creates local configuration. Use when: any other clawops tool reports that there is no config, or the user wants to add a second stack alongside the ones they have. This is the first call on a machine that has never run clawops — a fresh container, a new laptop, a sandbox. Adding a stack is additive and safe: existing stacks are kept. Overwriting one needs force: true, because changing a state backend orphans the Pulumi state it points at — the infrastructure stays up and clawops can no longer see or destroy it. For aws, gcp and azure, stateUrl can be omitted and clawops names a bucket from the account it can see; that needs cloud credentials in the environment, so in a sandbox pass stateUrl explicitly. The local provider needs host instead, and no cloud account at all. Do NOT use when: the user wants to deploy — that is clawops_up, after this. Credentials are never passed here: clawops reads them from the environment (R6).
clawops_hardenActionApply security hardening to a deployed stack: SSH, UFW, fail2ban, unattended-upgrades, the Docker socket, and per-cloud checks. Optionally join the stack to a Tailscale network and reach it there instead of over the public internet. Use when: the user asks to harden, secure, or lock down a stack; asks what the hardening report says (with dryRun: true, which changes nothing); or asks to put a stack on their tailnet. tailscale: true installs Tailscale, joins the tailnet as clawops-<stack>, and then moves clawops onto that address — but only after opening an SSH session to it, against host keys pinned over the connection already trusted. If that fails, nothing is recorded and the public address stays in use. The auth key comes from `clawops secret set TAILSCALE_AUTH_KEY` and is never passed through this tool (R6). tailscaleRevert: true takes the host back off the tailnet, over its public address. On a private-only stack it refuses and names the plan/apply commands that reopen SSH first — relay them rather than trying to work around it. To close the public ports afterwards, plan with privateOnly: true and apply that plan; this tool does not change firewall rules. Do NOT use when: the user wants to know whether a stack is healthy — that is clawops_doctor. Do NOT pass tailscale and tailscaleRevert together.
clawops_task_statusRead-onlyPoll the status of a long-running clawops task (returned by clawops_up, clawops_destroy, clawops_apply, etc.). Per R12 streaming model. Use when: the user is waiting on a long-running deploy/destroy and wants progress, OR you need to check whether a previously-started operation finished. Do NOT use when: there is no active taskId — start the operation first.
clawops_workflow_deploy_appActionSingle-tool workflow that takes a user from "I want to deploy OpenClaw to <provider>" to a verified, healthy gateway. Internally: plan → user confirms (elicitation) → up → wait for healthy → return URL. Use when: the user expresses end-to-end deployment intent ("deploy to AWS", "spin up an OpenClaw on GCP for me"). Do NOT use when: the user is mid-deployment and only needs one step (e.g., they already have a plan; use clawops_apply). Do NOT use for destroying or updating — separate workflows.
clawops_workflow_recoverRead-onlyDiagnostic workflow for an unhealthy stack. Internally: what is deployed (clawops_status) → the stack's failed health checks (clawops_doctor) → the gateway's last 50 log lines (clawops_logs_tail) → a report with next steps that name the tool for each kind of failure. Changes nothing. Use when: the user reports any "not working" symptom and you don't know where to start. Best entry point for troubleshooting. Do NOT use when: the user has already identified the problem and asks for a specific fix.
clawops_stacks_listRead-onlyList all clawops-managed stacks across all configured providers. With fleet: true, also reads every stack's host over SSH and reports its host agent: whether one is installed and running, which OpenClaw agent it serves, and, on a fleet member (ADR 0015), its tag, its peers, its firewall table and its tailnet state. Peers that cannot work are reported on the host that names them: a peer with no host agent, one that does not serve peers, one that answers a tag this host does not carry, or one reached by a name it does not have on the tailnet. Same reading as `clawops fleet status`. Changes nothing. On a host agent: this host and its fleet peers, and whether each peer answered. With fleet: true it reads this host and asks each peer to report itself, then checks them against each other the same way. A peer answers for itself only. Use when: the user wants an overview of their deployments, asks "what stacks do I have", or wants to compare stacks before an operation. With fleet: true, when they ask which host agents are running, whether the fleet is healthy, or why one host agent cannot reach another. Do NOT use when: the user named a specific stack — use clawops_status directly with that name. Do NOT pass fleet: true just to list stacks: it connects to every host and takes up to 30 s for one that does not answer.
clawops_stacks_deleteActionRemove a stack from ~/.clawops/config.json. This forgets the stack; it does not tear down its infrastructure, and it refuses a stack that is still deployed unless forced. Use when: the user wants to stop tracking a stack whose resources are already gone. Do NOT use when: the user wants the infrastructure removed — that is clawops_destroy, first. Forcing the delete of a deployed stack leaves resources running and billing that clawops can no longer see.
| clawops_apply | Apply a previously-generated Maker plan (deploy-plan.schema.json). Deterministic — the plan describes exactly what will be created. Use when: the user has a plan file path and wants to apply it. This is the agent-friendly path for any deploy/destroy operation. Do NOT use when: there's no plan file — generate one first with clawops_plan. | Action |
| clawops_plan | Generate a Maker deploy plan (does NOT apply). Plan is JSON conforming to deploy-plan.schema.json — review before applying. Use when: the user wants to see what would be created before committing, or you (the agent) need a reviewable artifact for the user to approve. Do NOT use when: the user has explicitly asked to deploy and you already have their approval — go directly to clawops_up. | Read-only |
| clawops_config_set | Set a configuration value on the remote OpenClaw gateway. Optionally restarts the gateway after. Use when: the user wants to change OpenClaw configuration (model provider, channel auth, gateway port). Do NOT use when: the user is reading config — use clawops_config_get. Do NOT bulk-edit; one key at a time so changes are auditable (R21). | Action |
| clawops_config_unset | Remove a configuration key from the remote OpenClaw gateway config, reverting it to the OpenClaw default. Use when: the user wants to delete a config key entirely (e.g., remove a channel, clear an override). Do NOT use when: the user wants to set the key to a new value — use clawops_config_set instead. | Action |
| clawops_config_validate | Validate the remote OpenClaw gateway config against the known schema. Checks for structural errors (wrong types, unknown top-level keys) that would cause OpenClaw to fail on startup. Use when: the user wants to verify config before restarting the gateway, or after editing openclaw.json manually. Do NOT use when: the user wants to change config — use clawops_config_set. | Read-only |
| clawops_gateway_restart | Restart the OpenClaw gateway daemon on the remote instance. Use when: a gateway-wide config change requires reload, or the gateway is reported as unresponsive. Note: OpenClaw 2.0 removed per-agent restart; `gateway restart` is the only restart it offers, and it affects every agent on the host. Brief downtime (~10s). | Action |
| clawops_gateway_update | Move the gateway to a different OpenClaw version: pull the image and restart the gateway on it. Every agent on the host restarts with it. Use when: the user asks to upgrade or downgrade OpenClaw on a running stack, naming a version. Do NOT use when: the user has not named a concrete version — moving tags such as `latest` are refused, as the CLI refuses them. Do NOT use without a backup the user can return to: suggest clawops_backup_create first. | Action |
| clawops_backup_create | Take a backup of the gateway's state (config, database, sessions, transcripts and installed plugins) and download it to a local archive. Live state is not changed. Use when: the user asks for a backup, and before anything that replaces state: a version update, a migration, a restore, or a plan that replaces the instance. Do NOT use when: the user wants to back up cloud infrastructure — Pulumi state and plans cover that, not this. | Action |
| clawops_backup_restore | Verify a backup archive and expand it on the host beside the live state, never over it. With activate: true, also put it into service: stop the gateway, swap the restored state in (keeping the state it replaces), restart, and roll back if the gateway does not answer. Use when: the user asks to restore or recover from a backup, naming the archive. Do NOT use when: the gateway is merely unhealthy — clawops_workflow_recover diagnoses that without discarding state. Restoring is time travel: everything since the backup is lost, and channel credentials may need relinking. | Action |
| clawops_migrate | Move a deployment from OpenClaw 1.x onto the 2.0 runtime contract: state ownership, config, and the gateway's run command, in the order a real migration showed works. Use when: a stack still runs OpenClaw 1.x and the user wants it on 2.x. clawops_doctor and clawops_gateway_status say which line a stack runs. Do NOT use when: the stack is already on 2.x — use clawops_gateway_update to change versions within 2.x. Take a backup first with clawops_backup_create. | Action |
| clawops_secret_delete | Delete a locally stored secret by name. Warns when a stack still references it. Use when: the user asks to remove a secret they no longer use. Do NOT use when: the user wants to replace a value — ask them to run `clawops secret rotate <NAME>`; no tool takes a secret value (R6). | Action |
| clawops_init | Register a stack and write ~/.clawops/config.json: the provider, the state backend, the region, and an SSH key pair generated if one is not already there. Nothing is provisioned and nothing is charged; this only creates local configuration. Use when: any other clawops tool reports that there is no config, or the user wants to add a second stack alongside the ones they have. This is the first call on a machine that has never run clawops — a fresh container, a new laptop, a sandbox. Adding a stack is additive and safe: existing stacks are kept. Overwriting one needs force: true, because changing a state backend orphans the Pulumi state it points at — the infrastructure stays up and clawops can no longer see or destroy it. For aws, gcp and azure, stateUrl can be omitted and clawops names a bucket from the account it can see; that needs cloud credentials in the environment, so in a sandbox pass stateUrl explicitly. The local provider needs host instead, and no cloud account at all. Do NOT use when: the user wants to deploy — that is clawops_up, after this. Credentials are never passed here: clawops reads them from the environment (R6). | Action |
| clawops_harden | Apply security hardening to a deployed stack: SSH, UFW, fail2ban, unattended-upgrades, the Docker socket, and per-cloud checks. Optionally join the stack to a Tailscale network and reach it there instead of over the public internet. Use when: the user asks to harden, secure, or lock down a stack; asks what the hardening report says (with dryRun: true, which changes nothing); or asks to put a stack on their tailnet. tailscale: true installs Tailscale, joins the tailnet as clawops-<stack>, and then moves clawops onto that address — but only after opening an SSH session to it, against host keys pinned over the connection already trusted. If that fails, nothing is recorded and the public address stays in use. The auth key comes from `clawops secret set TAILSCALE_AUTH_KEY` and is never passed through this tool (R6). tailscaleRevert: true takes the host back off the tailnet, over its public address. On a private-only stack it refuses and names the plan/apply commands that reopen SSH first — relay them rather than trying to work around it. To close the public ports afterwards, plan with privateOnly: true and apply that plan; this tool does not change firewall rules. Do NOT use when: the user wants to know whether a stack is healthy — that is clawops_doctor. Do NOT pass tailscale and tailscaleRevert together. | Action |
| clawops_task_status | Poll the status of a long-running clawops task (returned by clawops_up, clawops_destroy, clawops_apply, etc.). Per R12 streaming model. Use when: the user is waiting on a long-running deploy/destroy and wants progress, OR you need to check whether a previously-started operation finished. Do NOT use when: there is no active taskId — start the operation first. | Read-only |
| clawops_workflow_deploy_app | Single-tool workflow that takes a user from "I want to deploy OpenClaw to <provider>" to a verified, healthy gateway. Internally: plan → user confirms (elicitation) → up → wait for healthy → return URL. Use when: the user expresses end-to-end deployment intent ("deploy to AWS", "spin up an OpenClaw on GCP for me"). Do NOT use when: the user is mid-deployment and only needs one step (e.g., they already have a plan; use clawops_apply). Do NOT use for destroying or updating — separate workflows. | Action |
| clawops_workflow_recover | Diagnostic workflow for an unhealthy stack. Internally: what is deployed (clawops_status) → the stack's failed health checks (clawops_doctor) → the gateway's last 50 log lines (clawops_logs_tail) → a report with next steps that name the tool for each kind of failure. Changes nothing. Use when: the user reports any "not working" symptom and you don't know where to start. Best entry point for troubleshooting. Do NOT use when: the user has already identified the problem and asks for a specific fix. | Read-only |
| clawops_stacks_list | List all clawops-managed stacks across all configured providers. With fleet: true, also reads every stack's host over SSH and reports its host agent: whether one is installed and running, which OpenClaw agent it serves, and, on a fleet member (ADR 0015), its tag, its peers, its firewall table and its tailnet state. Peers that cannot work are reported on the host that names them: a peer with no host agent, one that does not serve peers, one that answers a tag this host does not carry, or one reached by a name it does not have on the tailnet. Same reading as `clawops fleet status`. Changes nothing. On a host agent: this host and its fleet peers, and whether each peer answered. With fleet: true it reads this host and asks each peer to report itself, then checks them against each other the same way. A peer answers for itself only. Use when: the user wants an overview of their deployments, asks "what stacks do I have", or wants to compare stacks before an operation. With fleet: true, when they ask which host agents are running, whether the fleet is healthy, or why one host agent cannot reach another. Do NOT use when: the user named a specific stack — use clawops_status directly with that name. Do NOT pass fleet: true just to list stacks: it connects to every host and takes up to 30 s for one that does not answer. | Read-only |
| clawops_stacks_delete | Remove a stack from ~/.clawops/config.json. This forgets the stack; it does not tear down its infrastructure, and it refuses a stack that is still deployed unless forced. Use when: the user wants to stop tracking a stack whose resources are already gone. Do NOT use when: the user wants the infrastructure removed — that is clawops_destroy, first. Forcing the delete of a deployed stack leaves resources running and billing that clawops can no longer see. | Action |
Configuration
AWS_PROFILE
| Name | Description | |
|---|---|---|
| AWS_PROFILE | — |
Automated checks
Ran Nov 16, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachabledfridkin/clawops is public and reachablegithub.com/dfridkin/clawops ↗Pass
- Package names this repository as its source@clawops/cli names dfridkin/clawops as sourcenpmjs.com/package/@clawops/cli ↗Pass
- Build provenance (Sigstore attestation)Sigstore attestation for @clawops/clinpmjs.com/package/@clawops/cli/v/2.5.0#provenance ↗Pass
- Open source license (OSI)MPL-2.0spdx.org/licenses/MPL-2.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-07github.com/dfridkin/clawops ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from @clawops/cliPass
- No critical advisory in the package or its dependencies363 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model30 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubclawops
MCP-native infrastructure ops for OpenClaw, with read-only mode, destructive-action confirmation, and audit logs built in.
clawops is a CLI and MCP server for deploying and operating self-hosted 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: 2.4 release notes below, and the full history in CHANGELOG.md.
Who this is for
- OpenClaw users who want the simplest path to self-hosting across cloud or local VMs, with reliable deploy, status checks, logs, backups, and upgrades in a single CLI.
- Claude Code / Cursor / MCP users looking for a real-world reference implementation of safe infrastructure operations through MCP. Typed tool schemas, read-only mode, destructive-action confirmation, and audit logs.
- Self-hosted AI and local-first developers who want to run their own AI assistant without committing to Kubernetes, a managed SaaS platform, or a single cloud provider.
What clawops does
- Provisions and tears down OpenClaw infrastructure on AWS, GCP, Azure, and local VMs using
the Pulumi Automation API. You do not install Pulumi; clawops installs the CLI it needs into
~/.clawops/.pulumi-clion first use. - Manages day-to-day operations: status, logs, SSH, tunnels, config, agents, gateway, backups.
- Exposes every operation as a typed MCP tool so AI agents can drive ops safely.
- Enforces a plan → review → apply discipline for cloud deployments.
- Emits JSON output everywhere (
--json) for scripting and automation. - Never stores cloud credentials. Reads them from your environment's existing CLI profiles.
What clawops does not do
- No high availability or clustering. Optimized for single-node deployments.
- No Kubernetes. It deploys to VMs, not container orchestration platforms.
- No OpenClaw skill/agent authoring. clawops manages infrastructure; what runs on it is up to you and OpenClaw.
- No TLS or domain automation (yet). Bring your own reverse proxy or see
docs/limitations.mdfor the manual path. - No credential storage. Cloud credentials must be configured in your environment before using
clawops. They are never written to
~/.clawops/config.json. - No native Windows. WSL2 is fully supported; see
docs/support-matrix.md.
Quick Start
npm install -g @clawops/cli
clawops setup
clawops setup is an interactive wizard that gets OpenClaw running in about 2 minutes. It
handles everything in one flow, no config files to write by hand, no commands to memorize.
What the wizard does
Step 1. Choose a deployment target
Pick an existing server you can SSH into (Linux or macOS), or a new cloud VM on AWS, GCP, or Azure. Cloud deployments walk you through authenticating with the provider CLI if you aren't already signed in.
Step 2. Pick an LLM provider
Choose from Anthropic, OpenAI, Amazon Bedrock, Ollama, or others. The wizard prompts for your
API key and saves it locally (in ~/.clawops/secrets/, chmod 600), it is never sent anywhere
except to OpenClaw on the target host when the config is applied.
Step 3. Add chat integrations (optional)
Select any combination of Discord, Telegram, Slack, WhatsApp, or Teams. The wizard collects each integration's bot token the same way as the API key. Paste it in, reference an env var, or point to a file.
Step 4. Wire your AI editor
Select which AI apps should have access to clawops. Claude Desktop, Claude Code, Cursor, Windsurf, VS Code, and Zed are all supported. The wizard writes an MCP server entry into each app's config file using the absolute binary path so the app can launch it independently.
Step 5. Deploy
The wizard bootstraps OpenClaw on the target host over SSH (installs Docker, pulls the image, starts the container), applies your LLM and integration config, generates a gateway auth token, and prints a direct dashboard URL:
✔ All done! OpenClaw is running.
ℹ Open dashboard: http://192.168.1.50:18789?token=<your-token>
ℹ Token saved to ~/.clawops/secrets/GATEWAY_TOKEN_my-stack
Prerequisites: Node.js ≥ 22, an SSH key, and either an SSH-reachable Linux/macOS host or a
cloud account with CLI credentials configured (aws configure, gcloud auth login, or az login).
You do not need Pulumi. The first cloud deployment installs the CLI clawops drives into
~/.clawops/.pulumi-cli and says so while it does.
For a full narrated walkthrough with example output, see docs/demo-script.md.
Manual setup, existing server
If you prefer step-by-step control, or are adding clawops to an already-running deployment:
npm install -g @clawops/cli
clawops doctor # verify environment
clawops init --provider local --host 192.168.1.50 --user ubuntu --key-path ~/.ssh/id_ed25519
clawops up # installs Docker + OpenClaw over SSH
clawops status
See docs/examples/local-vm.md for SSH prerequisites, firewall
setup, and troubleshooting.
Manual setup, cloud (AWS)
npm install -g @clawops/cli
# Requires AWS credentials in your environment (AWS_PROFILE or ~/.aws/credentials)
clawops init --provider aws
# Edit ~/.clawops/config.json: set stateUrl to your S3 bucket
clawops plan --provider aws --stack default --ssh-cidr auto --out /tmp/plan.json
clawops apply /tmp/plan.json
--ssh-cidr auto allows SSH from this machine's public IP, resolved while the plan is
generated and written into it. Without it the plan allows no ingress at all and nothing,
including clawops, will be able to connect.
Connect an AI editor
The setup wizard handles this automatically (Step 4). To wire or re-wire editors at any time:
clawops mcp install
This opens the same interactive checkbox used in the wizard, select Claude Desktop, Claude Code, Cursor, Windsurf, VS Code, or Zed and clawops writes the MCP entry into each app's config using the correct absolute binary path.
To add the entry manually instead, paste this into your editor's MCP config:
{
"mcpServers": {
"clawops": {
"command": "npx",
"args": ["-y", "@clawops/cli", "mcp", "serve", "--read-only"]
}
}
}
That form needs nothing on $PATH and is what a directory or an installer will copy. If you
would rather point at the binary you already have, use its absolute path — the output of
which clawops — with the same arguments:
{
"mcpServers": {
"clawops": {
"command": "/path/to/clawops",
"args": ["mcp", "serve", "--read-only"]
}
}
}
Either way, pass the arguments. mcp serve is what speaks the protocol, and an explicit config
is one that still reads clearly a year later. clawops does not strand a client that omits them:
run with no command at all and a pipe on stdin — how every MCP client starts a server — and it
starts mcp serve, saying so on stderr. Typed at a terminal, clawops still prints help.
Pass cloud credentials in env. A client starts the server with the environment its config
gives it, not your shell's, so an AWS_PROFILE exported in a terminal does not reach it, and
every tool that reads a stack fails with "Could not read the state of stack". Name the profile,
or the variables your state backend needs, in the server's env block:
{
"mcpServers": {
"clawops": {
"command": "npx",
"args": ["-y", "@clawops/cli", "mcp", "serve"],
"env": { "AWS_PROFILE": "my-profile" }
}
}
}
It holds a profile name, not a key: the credentials themselves stay where the cloud CLI keeps them (R6).
Config file locations:
| App | Path |
|---|---|
| Claude Desktop (macOS) | ~/Library/Application Support/Claude/claude_desktop_config.json |
| Claude Desktop (Linux) | ~/.config/Claude/claude_desktop_config.json |
| Claude Code | ~/.claude.json |
| Cursor | ~/.cursor/mcp.json |
| Windsurf | ~/.codeium/windsurf/mcp_config.json |
| VS Code (macOS) | ~/Library/Application Support/Code/User/mcp.json |
| VS Code (Linux) | ~/.config/Code/User/mcp.json |
| Zed | ~/.config/zed/settings.json (key: context_servers) |
Start with --read-only. It enables status, logs, config reads, and diagnostics while
blocking mutations. Remove it only after reviewing
docs/security/mcp-safety.md.
Destructive tools (clawops_destroy, clawops_up, clawops_config_set, etc.) require explicit
confirmation before executing, they will never run silently.
For HTTP mode setup see docs/mcp/.
Day-to-day operations
clawops status # Stack outputs: IP, gateway URL, SSH info
clawops logs -f # Tail OpenClaw logs over SSH
clawops ssh # Interactive SSH session
clawops ssh --command "docker ps"
clawops config get maxAgents
clawops config set maxAgents 8
clawops tunnel # Port-forward gateway UI to localhost
clawops destroy --yes # Destroy cloud-provider stack
clawops down --yes # Destroy local-provider stack
Commands
| Command | Description |
|---|---|
setup |
First-run wizard: guided LLM, integrations, spending limits, and deploy-plan generation |
init |
Register a stack in ~/.clawops/config.json without provisioning. Additive, existing stacks are kept; --force is needed only to overwrite one |
up |
Provision or update stack (--dry-run for preview, --gateway-port for a non-default port) |
down |
Destroy local-provider stack (requires --yes; --dry-run shows current outputs) |
destroy |
Destroy cloud-provider stack with confirmation prompt (--dry-run shows current outputs) |
status |
Show stack outputs: IP, gateway URL, region, provisioned time, and any requests the stack's host agent left for you |
plan |
Generate a deploy-plan JSON artifact (dry-run safe). --ssh-cidr <list|auto> and --gateway-cidr decide who may connect; --publish-gateway loopback|all decides what is listening; --private-only closes public access on a stack reached over its tailnet |
apply |
Apply a previously reviewed plan file (--dry-run validates and shows diff without applying) |
ssh |
Interactive SSH session or run a remote command |
logs |
Stream OpenClaw logs (-f, --tail N, --since 5m) |
tunnel |
Local port-forward to gateway UI over SSH |
config |
Get/set remote OpenClaw config values (--dry-run shows would-write JSON) |
agents |
List OpenClaw agents, or stream one agent's logs |
agent install |
Install a host agent on a stack's gateway host, for one OpenClaw agent only the operator can reach (--agent, --operator <channel>:<peer>, --allow handoff tools, --strict). Refuses unless the gateway's routing allows only the operator; denies clawops to every other agent. --serve-peers <tag> and --peer <stack>=<tailnet name> make the host a fleet member, whose host agent reads its peers over the tailnet (2.5, ADR 0015; see Operations) |
agent uninstall |
Remove the host agent and unwire the gateway (--purge also removes its audit log) |
fleet status |
Read every stack's host over SSH and list its host agent: running or not, which OpenClaw agent it serves, and on a fleet member its tag, peers, firewall table and tailnet state. Reports peers that cannot work, on the host that names them. --stack a,b reads only those; --json. A stack with nothing deployed is listed as such. Exits 1 when any host has a problem or does not answer |
gateway |
Restart the OpenClaw gateway service |
backup |
Create and restore OpenClaw state backups (restore expands into a staging directory, never in place; --activate swaps it in and rolls back if the gateway does not come up) |
stacks |
List named stacks and their state |
doctor |
Check the local machine; with --stack, the deployment's health too; with --provider, one cloud's credentials and account setup whether or not a stack exists; with --instance-type, account checks ask about that size rather than the provider default. --json for the report. Exits 1 on any failure |
secret |
Manage secrets: list, set, delete, rotate, audit |
monitor |
Live dashboard: gateway health, container stats, log tail, stack picker |
mcp serve |
Start the embedded MCP server (stdio, or HTTP with --http <port> --token <t>). --host-agent serves a gateway host's own agent (ADR 0014) |
mcp install |
Interactively wire clawops into AI editors |
mcp wire |
Wire the gateway's AI as an MCP client of clawops (verifies the connection before saving) |
help |
List all commands and global flags |
harden |
Apply security hardening to a deployed stack (SSH, UFW, fail2ban, unattended-upgrades, Docker socket; AWS: SG audit, SSM check, Flow Logs, GuardDuty). --tailscale joins the stack to your tailnet and moves clawops onto that address once it answers; --tailscale-revert undoes it |
bug |
Open a pre-filled GitHub issue with system context from doctor |
Full flag reference: clawops <command> --help
Plan → Apply workflow
For non-local providers, clawops enforces a review-before-apply discipline:
# 1. Generate a plan: runs `pulumi preview` internally, produces JSON
# --ssh-cidr decides who may connect. `auto` means this machine; omit it and nobody can.
clawops plan --provider aws --region us-east-1 --ssh-cidr auto --out /tmp/plan.json
# 2. Review plan.json: the `diff` field shows projected changes at plan-generation time
cat /tmp/plan.json | jq .diff
# 3. Apply: reads and validates the plan file, then runs `pulumi up`
clawops apply /tmp/plan.json
# Without --yes, apply prompts: "Continue? (y/N)"
clawops apply /tmp/plan.json --yes # skip prompt in automation
The plan JSON conforms to spec/deploy-plan.schema.json (AJV-validated) and captures reviewed
intent: provider, region, instance type, CIDR ranges, and OpenClaw version. apply re-runs
pulumi up using those parameters against the current live state, it does not replay a locked
execution artifact. Review and apply in the same session to minimize drift risk.
See docs/plan-apply.md for full semantics, drift guidance, and the safe CI pattern.
MCP server
clawops ships an embedded MCP server. Claude Code, Cursor, and any MCP-compatible agent can drive deployments without leaving the chat interface.
Wire your editor
clawops mcp install # interactive checkbox: writes config for selected apps
The wizard resolves the absolute binary path automatically so app launchers can find clawops
without inheriting your shell's PATH. See Connect an AI editor above
for manual config paths.
Wire the gateway AI
The OpenClaw gateway runs its own AI agent. Once wired, that agent can call clawops directly instead of guessing at infrastructure state:
clawops mcp wire --stack prod # openclaw mcp add, which connects before it saves
Requires OpenClaw 2026.7.1-2 or later on the gateway. The clawops setup wizard offers this
step after a successful deploy.
Every agent on the gateway gets every clawops tool, including the default agent, which
answers anyone who can message the gateway. OpenClaw's MCP servers are gateway-wide. After
wiring, mcp wire names each agent that can now call clawops. To keep one away, add
"clawops__*" to its agents.entries.<id>.tools.deny. For an agent that hands destructive
changes back to you instead of making them, use clawops agent install.
Stdio mode (Claude Code / Cursor / VS Code)
Start the server manually or confirm your config is correct:
clawops mcp serve --read-only # safe for first evaluation
clawops mcp serve # full mode: enables provisioning, config write, ssh exec
HTTP mode (remote / multi-client)
clawops mcp serve --http 3333 --bind 127.0.0.1
# MCP HTTP server listening on 127.0.0.1:3333
Do not bind to a non-loopback address without additional authentication controls in front of it.
Available tools
| Tool | Toolset | Description |
|---|---|---|
clawops_status |
cli | Show stack outputs (what is deployed, not whether it works) |
clawops_doctor |
cli | Run diagnostics: local prerequisites, and with a stack, remote health |
clawops_logs_tail |
cli | Tail OpenClaw logs |
clawops_monitor |
cli | Sample gateway and host metrics |
clawops_stacks_list |
admin | List all stacks and their state; with fleet: true, every host agent and the fleet's peers, as clawops fleet status reports them |
clawops_config_get |
cli | Read a remote config value |
clawops_agents_list |
cli | List running agents |
clawops_agents_logs |
cli | One agent's recent activity, paginated |
clawops_gateway_status |
cli | Whether the gateway container is running, and its image |
clawops_secret_list |
cli | List stored secrets by name and status (never values) |
clawops_secret_audit |
cli | Report missing secrets and unresolvable $secret: references |
clawops_up |
cli | Provision or update a stack |
clawops_destroy |
cli | Destroy a stack (elicits confirmation) |
clawops_apply |
cli | Apply a plan file |
clawops_plan |
cli | Generate a deploy plan |
clawops_config_set |
cli | Write a remote config value |
clawops_config_unset |
cli | Remove a remote config key |
clawops_config_validate |
cli | Validate the deployed config against the OpenClaw schema |
clawops_gateway_restart |
cli | Restart the gateway (elicits confirmation) |
clawops_gateway_update |
cli | Move the gateway to a concrete OpenClaw version (elicits confirmation) |
clawops_backup_create |
cli | Back up gateway state to a local archive |
clawops_backup_restore |
cli | Restore a backup to staging, or with activate into service (elicits confirmation) |
clawops_migrate |
cli | Migrate a 1.x deployment onto the 2.0 runtime (elicits confirmation) |
clawops_stacks_delete |
admin | Forget a stack in config; does not destroy infrastructure (elicits confirmation) |
clawops_secret_delete |
cli | Delete a stored secret (elicits confirmation) |
clawops_harden |
cli | Apply hardening modules; join or leave a tailnet (elicits confirmation) |
clawops_init |
cli | Register a stack and write ~/.clawops/config.json (no cloud resources) |
clawops_workflow_deploy_app |
workflow | End-to-end deploy: plan → confirm → apply → status |
clawops_workflow_recover |
workflow | Diagnose an unhealthy stack: status, failed health checks, recent logs, and which tool fixes what |
clawops_task_status |
cli | Poll a long-running task |
Tools in the read toolset are also available in --read-only mode; the table's Toolset column shows the primary toolset. All other toolsets require full mode.
Destructive tools require explicit confirmation (elicitation) unless yes: true is passed.
See docs/security/tool-risk-matrix.md for the full risk
classification of every tool.
Configuration
Config lives at ~/.clawops/config.json (override with $CLAWOPS_HOME).
{
"version": 1,
"defaults": {
"provider": "aws",
"stack": "default"
},
"stacks": {
"default": {
"provider": "aws",
"region": "us-east-1",
"stateUrl": "s3://my-clawops-state"
}
},
"ssh": {
"keyPath": "~/.clawops/id_ed25519",
"knownHostsPath": "~/.clawops/known_hosts"
}
}
Cloud credentials are never stored in config. Clawops reads them from the environment:
| Provider | Credential source |
|---|---|
| AWS | AWS_PROFILE or standard AWS credential chain (~/.aws/credentials) |
| GCP | GOOGLE_APPLICATION_CREDENTIALS or gcloud auth application-default login |
| Azure | AZURE_CLIENT_ID / AZURE_CLIENT_SECRET or az login |
| Local | SSH host + key configured in stacks[name].localOpts |
Spending limits
An optional policy block limits what clawops will deploy from this machine, whichever tool asks:
"policy": {
"allowedInstanceTypes": { "aws": ["micro", "small"] },
"maxStacks": 3
}
plan, apply and up refuse a server size outside allowedInstanceTypes for that provider
(a clawops size or the provider's own type; small and t3.small are the same on AWS), and
init refuses a new stack beyond maxStacks. Every MCP tool that deploys is held to the same
limits, in the same words, and no tool can change them. clawops setup asks whether to set
them, then offers only the sizes you allowed. The limit lives here rather than in the plan
because a plan is what an agent writes.
Known limitations
See docs/limitations.md for the full list. Key points:
- Single-node deployments only, not a high-availability or clustering platform.
clawops applyis not an immutable plan execution. Seedocs/plan-apply.md.- No TLS/domain automation in the current release.
- MCP tools execute privileged operations, use
--read-onlyfor first evaluation.
Architecture
clawops
├── src/cli/ citty-based commands (one file per verb)
├── src/config/ ~/.clawops/config.json management
├── src/providers/ Cloud adapters (AWS, GCP, Azure, local)
│ ├── aws/ Pulumi inline program + ProviderAdapter
│ ├── gcp/
│ ├── azure/
│ └── local/ SSH bootstrap (no Pulumi)
├── src/pulumi/ Pulumi Automation API wrapper + output helpers
├── src/transport/ SSH client (ssh2) + connection pool + tunnels
├── src/mcp/ MCP server, tool handlers, progress tracking
├── src/plan/ Maker plan generation, AJV validation, apply
├── src/output/ ASCII table, spinner, JSON, human-readable output
├── src/errors/ Typed error hierarchy with exit codes
└── spec/ Machine-readable ground truth (JSON Schema, YAML)
Key design decisions:
- Pulumi Automation API: the user installs no Pulumi. Clawops installs the CLI the API drives into
~/.clawops/.pulumi-cli, pinned to the bundled SDK, without editing$PATH(ADR 0010); Pulumi home is sandboxed to~/.clawops/.pulumi; stack programs are inline TypeScript closures - State in cloud blob storage: GCS (
gs://), S3 (s3://), Azure Blob, no local state files, nopulumi.yaml - SSH via
ssh2: never shells out to/usr/bin/ssh; TOFU host verification against~/.clawops/known_hosts; connection pool with 5-min idle TTL - Plan → apply discipline: every non-local deployment goes through
generatePlan()→ review →applyPlan(); destructive changes always require human review of the plan JSON - MCP-first: every CLI operation has a typed MCP tool; schemas generated from
spec/mcp-tools.yaml; all destructive tools use elicitation
See docs/architecture.md for a full narrative, and docs/decisions/ for ADRs.
clawops MCP questions
How do I add clawops MCP to Claude Code?
Run claude mcp add clawops -- npx -y @clawops/cli mcp serve in your terminal. Add --scope user to make it available in every project.
How do I add clawops MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does clawops MCP provide?
It exposes 30 tools, including clawops_status, clawops_doctor, clawops_logs_tail, clawops_monitor, clawops_config_get.
Where are cloud credentials stored?
clawops never stores cloud credentials; it reads them from your environment's existing CLI profiles.
Does clawops support Kubernetes?
No, clawops is optimized for single-node deployments to VMs rather than container orchestration platforms.
Can I use clawops with Claude Code or Cursor?
Yes, it provides typed MCP tools that allow AI agents like Claude Code and Cursor to drive infrastructure operations safely.
Is there a way to prevent accidental destructive actions via MCP?
Yes, you can start with read-only mode to enable diagnostics while blocking mutations, and destructive tools require explicit confirmation.