ClawSprawl is the Astro-based operations surface for autonomous agent swarms. It combines a terminal-themed narrative shell with a live dashboard connected to the OpenClaw gateway via server-side SSR integration.

Default indexing posture: pages are shipped with noindex, nofollow meta robots tags because ClawSprawl is an internal operations surface by default.

• Start here: docs/README.md
• Visual architecture and Mermaid flows: docs/architecture-overview.md
• Deployment, environment, and npm operations (canonical): docs/deployment-guide.md
• Architecture and roadmap: docs/technical-design-plan.md
• Incident response and recovery (canonical): docs/operations-runbook.md
• API/sourcecode docs: docs/heredoc-api-sourcecode.md
• Extensions: docs/extensions.md
• Release and policy: CHANGELOG.md, VERSIONING.md, SECURITY.md

npm install
npm run dev

The app runs at http://localhost:4321. Copy .env.example to .env, set OPENCLAW_GATEWAY_TOKEN, and pick a CLAWSPRAWL_MODE (public, token, or insecure).

ClawSprawl uses an SSR boundary: browser clients call ClawSprawl APIs, and the server talks to the OpenClaw gateway.

• Gateway service: src/lib/gateway/server-service.ts
• Public APIs: src/pages/api/public/
• Private APIs: src/pages/api/private/
• Dashboard bootstrap runtime: src/lib/dashboard/bootstrap.ts

Design details and data flow live in docs/technical-design-plan.md.

ClawSprawl keeps gateway credentials server-side only.

• OPENCLAW_GATEWAY_TOKEN is read by the SSR server and never exposed to the browser.
• Public cards load through /api/public/* routes.
• In token mode, private cards unlock through /api/private/session and a secure httpOnly session cookie.
• insecure mode is for private-network deployments only.

Operational setup guidance: docs/deployment-guide.md. Incident guidance: docs/operations-runbook.md.

Public locked state:

Private unlocked state:

• Click either thumbnail to open the full-size screenshot.
• Mobile public locked view: main-overview-mobile-public-locked.png
• Mobile private unlocked view: main-overview-mobile-private-unlocked.png

Profiles control branding and identity chrome; live operational data always comes from the gateway.

• Built-in profiles: src/config/profiles/public-demo.ts, src/config/profiles/sprawl-lab.ts
• Profile index: src/config/profiles/index.ts
• Local private profiles use *.local.ts and stay gitignored.

Initialize a local profile scaffold:

npm run profile:local:init

The dashboard ships with 6 built-in dark-mode themes. Switch via the theme selector in the top-right corner of the dashboard — your choice persists in the browser via localStorage.

• Built-in themes: sprawl (default), cyberpunk, midnight, ember, mono, slate
• Theme presets: src/config/themes/presets.ts
• Server default: PUBLIC_CLAWSPRAWL_THEME=sprawl in .env

Set the server-default theme via the ops CLI:

npm run ops -- theme list
npm run ops -- theme set midnight

Recommended release gate:

npm run qa:strict

Additional commands:

npm run test
npm run build
npm run test:e2e

Coverage targets are enforced in CI:

• Unit coverage: 84%+ via npm run test:unit:coverage
• E2E runtime coverage: 80%+ via npm run test:e2e:coverage
• Docs coverage: 98%+ via npm run test:docs:coverage

Regenerate documentation screenshots:

npm run docs:screenshots

Images are stored in docs/screenshots/.

• npm package publish workflow: .github/workflows/publish-gpr.yml
• GHCR container publish workflow: .github/workflows/publish-container.yml

• Contribution guide: CONTRIBUTING.md
• Code of conduct: CODE_OF_CONDUCT.md
• Security policy: SECURITY.md
• Support policy: SUPPORT.md
• Agent conventions: AGENTS.md
• License: LICENSE