Clawdmin is a remote-administration layer for OpenClaw that works wherever your instances already live — a datacenter rack, a developer's laptop, a kiosk behind a hotel captive portal. One binary runs on each machine, polls home on its own schedule, and executes declaratively-defined operations with a rollback guarantee. No inbound ports, no VPN, no separate control plane.

Why Clawdmin

• Works on any network. Clients poll outbound over HTTPS. There are no inbound ports to forward and no VPN mesh to maintain — a laptop behind a captive portal is as manageable as a cloud VM. A heartbeat delivers full health; a fast tickle (HEAD /tickle/<id>.txt) cuts the response time to seconds without keeping a connection open.
• Never leaves a system dark. Every mutating operation snapshots the affected files and external state before it runs. A failure during execute or verify rolls the whole transaction back, then actively confirms the OpenClaw gateway is healthy again. The only way to land in a broken state is for rollback itself to fail — and the system is flagged unrecoverable and surfaced to an admin instead of left to decay quietly.
• Signed, not scripted. The hub never ships code to clients. It ships Ed25519-signed intent manifests — metadata only — and clients will only execute operations they have both a built-in handler for AND a valid signed authorization from a trusted key. Arbitrary command execution isn't a feature you can turn on.
• Agent-friendly by design. Every operation is a typed HTTP intent on a Local API that only accepts connections from the same machine. OpenClaw agents and any script on the machine queue work through the same dispatcher the dashboard uses, and inherit the same snapshot / verify / rollback guarantees. No shelling out and parsing stdout, no guessing whether the command actually worked.
• Drop-in OpenClaw skill. Clawdmin ships with an OpenClaw skill — skill/clawdmin-api/ — and auto-installs it into ~/.openclaw/skills/ on startup. Plain text instructions, no code. Any agent on the machine picks it up through OpenClaw's normal skill-loading path and can check its own gateway health, restart the process it's running on, enable a sibling agent, or report drift. Administration from inside OpenClaw, with the same reliability guarantees a human admin gets from the dashboard. No separate install step.
• Compliance is a first-class concept. Clients continuously report canonical RFC-8785 SHA-256 hashes of their installed skills, plugins, and agents. The hub compares against the deployed profile and shows drift in real time. Additive mode enforces a baseline; strict mode actively removes anything not on the list.
• One binary, three roles. The same install acts as a standalone client, a managed client, or a hub based on config. No "agent" package and "controller" package to version-skew against each other.
• Security-first admin surface. Password + TOTP with bcrypt, rate-limited logins with account lockout, recovery codes with forced TOTP rotation on redemption, last-admin-protection guards against locking yourself out, and an append-only audit log that can't be retroactively rewritten through the API.

Requirements

• OpenClaw ≥ 2026.4.15. Older versions lack intent manifests that Clawdmin relies on.
• Node.js 22 LTS. Strictly 22 — pinned via .nvmrc and engines. pnpm install refuses to proceed on anything else.
• macOS or Linux. Windows isn't supported natively; use WSL or Docker Desktop.
• Docker is a first-class alternative on any host OS.
• Postgres 16 for hub mode. Client-only nodes use bundled SQLite — no separate install.

Three ways to run

| Mode | When | Auth | Data | |---|---|---|---| | Standalone | Client with no hub URL set (default fresh install) | None (localhost trusted) | SQLite at ~/.clawdmin/clawdmin.db | | Managed client | Client enrolled with a hub | None locally; hub holds fleet record | SQLite for local op history | | Hub | Hub role enabled | Password + TOTP (RFC 6238) for admins | Postgres 16 |

Quickstart

Two install paths — pick one:

# A) One-liner (macOS / Linux): checks Node 22, installs, prints next steps.
curl -fsSL https://clawdmin.ai/install.sh | bash

# B) Plain npm if you already have Node 22 set up.
npm install -g clawdmin

Standalone client (self-hosters, one-machine setup)

clawdmin start                   # runs in background; logs at ~/.clawdmin/clawdmin.log
open http://localhost:7432/

No hub, no auth, full local management UI. SQLite stores operation history. clawdmin start daemonizes by default (matching openclaw start); use clawdmin logs to tail, clawdmin stop to shut down, and clawdmin start --foreground when running under Docker / systemd / launchd.

Managed client (enrolled with a hub)

clawdmin enroll https://hub.example.com <enrollment-token>
clawdmin start                   # starts server with poll loops active

The client both checks a tickle file every 15 seconds for fast wakeups and polls the hub on a heartbeat for complete updates.

Hub

export DATABASE_URL=postgres://clawdmin:clawdmin@localhost:5432/clawdmin
export CLAWDMIN_HUB_ENABLED=true
# Using the default registry (registry.clawdmin.ai)? Its signing key is
# bundled with Clawdmin — no CLAWDMIN_TRUSTED_KEYS needed. Self-hosting
# a registry? Set CLAWDMIN_TRUSTED_KEYS=$(cat signing.pub) before starting.

clawdmin db:migrate              # apply schema
clawdmin db:seed                 # seeds the non-authenticatable 'system' admin row
clawdmin admin:create            # interactive: creates your first login — save the TOTP URI and recovery codes it prints
clawdmin start --foreground      # start the hub under systemd/launchd; drop --foreground for a detached daemon on your laptop

The hub's admin API + dashboard listen on port 7433 (reachable over the network); the Local API listens on port 7432 bound to localhost only.

For declarative provisioning (Docker Compose, Kubernetes), set CLAWDMIN_INITIAL_ADMIN_USERNAME + CLAWDMIN_INITIAL_ADMIN_PASSWORD instead of running admin:create. See docs/operations.md. See docs/deployment.md for Docker, systemd, and launchd.

Architecture at a glance

┌──────────────────────────────────────────────────────────────────┐
│                       Clawdmin process                           │
│                                                                  │
│  ┌──────────────────────┐       ┌────────────────────────────┐   │
│  │ Local server         │       │ Hub server (conditional)   │   │
│  │ localhost only :7432 │       │ public interface :7433     │   │
│  │ No auth              │       │ Password+TOTP / API tokens │   │
│  │ POST /intent         │       │ /clients, /tickets,        │   │
│  │ GET  /status         │       │ /profiles, /audit-events   │   │
│  └──────────────────────┘       └────────────────────────────┘   │
│             │                              │                     │
│             └──────────┬───────────────────┘                     │
│                        ▼                                         │
│           ┌───────────────────────┐                              │
│           │   Handler runtime      │                             │
│           │  snapshot→execute→     │                             │
│           │  verify→rollback       │                             │
│           └───────────────────────┘                              │
│                        │                                         │
│       ┌────────────────┼────────────────┐                        │
│       ▼                ▼                ▼                        │
│   Dispatcher       Local intents      Snapshot                   │
│   (manifest +      (gateway.restart,  manager                    │
│    handler)         agent.create,…)                              │
└────────────────────────────────────────────────────────────────┘
                         │
                         ▼
               Signed intent manifests
           (fetched from the handler registry,
            Ed25519-verified at runtime)

Two HTTP servers in one process. Security boundary is bind(), not middleware.

See docs/architecture.md for the full picture.

Documentation

| Doc | For | |---|---| | docs/architecture.md | Anyone trying to understand the system | | docs/api.md | Integrators consuming the Local API or Hub Management API | | docs/configuration.md | Operators configuring a node | | docs/deployment.md | Operators deploying to Docker / systemd / launchd | | docs/operations.md | Admins using the hub day-to-day | | docs/security.md | Security reviewers, threat model | | docs/development.md | Contributors | | CONTRIBUTING.md | Pull requests, adding intents, testing |

Tech stack (pinned for v1)

• Node.js 22 LTS · TypeScript strict + noUncheckedIndexedAccess
• Express 5 · Zod · bcrypt · otpauth
• Postgres 16 via pg (no ORM, hand-written SQL)
• SQLite via better-sqlite3
• React 19 + Vite 6 + React Router v7
• Vitest, ESLint (typescript-eslint strict type-checked)
• pnpm 10

Repository layout

src/
  canonical/      RFC 8785 canonical JSON + SHA-256 hashing
  client/         Enrollment credentials read/write
  compliance/     Profile deploy composer, compliance evaluator, upgrade preflight
  config/         Node config schema + env var loader
  db/             Postgres pool, migration runner, query modules
  handlers/       Handler runtime (signature verify, dispatch, snapshot, rollback)
  intents/        The 46 built-in intent implementations
  maintenance/    Nightly job + ClawHub catalog freshener
  operations/     Local /intent operation dispatcher
  poll/           Heartbeat + tickle loops
  schemas/        Zod schemas for API types
  server/
    hub/          Hub Management API (public, authenticated)
    local/        Local API (localhost only, no auth)
  storage/        StorageInterface + SQLite + Postgres backends
  tickle/         Hub-side tickle file manager
dashboard/        React SPA (served by both servers)
deploy/           Dockerfile, systemd unit, launchd plist, deploy docs

Testing

pnpm install
pnpm typecheck
pnpm lint
pnpm test
pnpm build

198 unit + integration tests plus 6 end-to-end tests covering canonical hashing, schemas, handlers, snapshots, storage, poll loops, compliance, profile state, auth + recovery flows, the operation dispatcher, registry key trust, and the full login/recover/rotate browser journey. See docs/development.md for the full harness.

Relationship to the handler registry

Clawdmin fetches signed intent manifests from a separate service, the handler registry. The registry publishes authoritative metadata (which intents exist, at which OpenClaw + Clawdmin versions, with what safety level). The client holds the actual implementations.

• Public registry: https://registry.clawdmin.ai
• Registry source: humcrush/clawdmin-handler-registry (currently private)
• Public registry signing key (bundled with this release, verify against clawdmin registry:info): sha256:6cbc10ef8bd259a674bed784c76fce4711c6ca33d00c2e4a6eed2273afc124b6

Clawdmin ships with the public registry's Ed25519 key built in, so using the default registry requires no extra config. For self-hosted registries, set CLAWDMIN_TRUSTED_KEYS to your own PEM. Details in docs/security.md.

Adding a new intent requires both a manifest entry in the registry and an implementation in src/intents/. See CONTRIBUTING.md.

License

Licensed under the Apache License, Version 2.0. Contributions are accepted under the same license via a Developer Certificate of Origin sign-off (git commit -s); no CLA is required.

Security

Report security issues privately to [email protected]. See SECURITY.md for the full policy and docs/security.md for the threat model.