AgentSpan  ·  v0.01

Embedded control plane for local AI agents — one-command onboarding, multi-tenant runtime, workspace adapters, and a React UI with room for 2D/3D simulation.

Overview

AgentSpan is a self-hosted web interface that connects to a running OpenClaw Gateway over WebSocket and gives you a real-time operational view of your agent fleet.

Agent Adapters ──► AgentSpan Server (Express + Embedded PGlite)
                           │
               ┌───────────┴───────────┐
           React UI (Vite)         REST + SSE API
                                   /api/agents
                                   /api/tasks
                                   /api/runs
                                   /api/live

Stack: Node 24 · Express 5 · React 19 · Vite 7 · Embedded PGlite · TypeScript

The old root app/ and src/ implementation is now treated as legacy reference code. Active product development happens in apps/* and packages/*.

Quickstart

npx agentspan onboard --yes

Open http://127.0.0.1:3100.

No external Postgres setup is required. AgentSpan creates an embedded local runtime in ~/.agentspan, initializes the database automatically, and starts the control plane.

Daily use after onboarding:

npx agentspan run

Update an existing local install to the newest published package:

npx agentspan update

Manual developer install remains available:

git clone https://github.com/danyanovich/agentspan.git
cd agentspan
npm install
npm run onboard

The simplest setup is local:

• OpenClaw is already running on the same machine
• the gateway token is already stored in ~/.openclaw/openclaw.json
• AgentSpan auto-connects on startup with no browser-side setup

Install via OpenClaw

For end users, the main path should be OpenClaw itself.

Ask OpenClaw:

Install AgentSpan for me! http://127.0.0.1:3010/skill

After installation, OpenClaw should manage these commands:

• /agentspan — install if needed, start if needed, then open the dashboard
• /agentspan stop — stop the dashboard
• /agentspan status — show whether it is installed/running and the local URL

The OpenClaw-first lifecycle is on-demand by default, so AgentSpan only runs when the user asks for it.

Connection Model

AgentSpan is config-only. It does not store dashboard tokens or gateway credentials at runtime.

Gateway connection sources:

1. CLAWDBOT_API_TOKEN
2. OPENCLAW_CONFIG_PATH -> gateway.auth.token
3. ~/.openclaw/openclaw.json -> gateway.auth.token

Host configuration sources:

• OPS_UI_HOSTS_JSON for explicit multi-host setups
• otherwise a single host from CLAWDBOT_URL with default ws://127.0.0.1:18789

Multi-Host

For multiple OpenClaw gateways, configure them once via OPS_UI_HOSTS_JSON.

OPS_UI_DEFAULT_HOST_ID=local
OPS_UI_HOSTS_JSON=[{"id":"local","name":"Local OpenClaw","gatewayUrl":"ws://127.0.0.1:18789","gatewayTokenEnv":"CLAWDBOT_API_TOKEN","enabled":true}]

The UI can switch the active host and reconnect, but it does not edit host credentials from the browser.

Remote Access

Remote mode is intended for loopback + reverse proxy.

Run the production bundle and keep OPS_UI_HOST=127.0.0.1, then put Caddy/Nginx/Tailscale/Cloudflare Access in front.

Recommended topology:

• keep OPS_UI_HOST=127.0.0.1
• put Caddy/Nginx/Tailscale/Cloudflare Access in front
• leave OPS_UI_REMOTE_ALLOW_DANGEROUS_ACTIONS=false unless you explicitly want destructive actions

For a full remote deployment example, see docs/DEPLOY_REMOTE.md.

Environment Variables

| Variable | Default | Description | |---|---|---| | OPS_UI_MODE | local | local or remote mode | | OPS_UI_PORT / PORT | 3010 | HTTP server port | | OPS_UI_HOST / HOST | 127.0.0.1 | Bind address | | OPS_UI_TRUST_PROXY | false | Trust reverse proxy headers | | OPS_UI_REMOTE_ALLOW_DANGEROUS_ACTIONS | false | Allow destructive actions in remote mode | | OPS_UI_DEFAULT_HOST_ID | local | Default active OpenClaw host id | | OPS_UI_HOSTS_JSON | — | Multi-host OpenClaw config JSON array | | CLAWDBOT_URL | ws://127.0.0.1:18789 | OpenClaw Gateway WebSocket URL | | CLAWDBOT_API_TOKEN | — | Explicit gateway auth token | | OPENCLAW_CONFIG_PATH | — | Path to OpenClaw config file | | OPS_UI_MAX_QUEUE | 5000 | In-memory event queue cap |

API Reference

Monitor

GET  /api/monitor/sessions
GET  /api/monitor/runs
GET  /api/monitor/runs/:runId/events
GET  /api/monitor/graph?window=3600
GET  /api/monitor/diagnostics
GET  /api/monitor/events
POST /api/monitor/connect
POST /api/monitor/disconnect
POST /api/monitor/refresh-sessions
POST /api/monitor/abort

Hosts

GET  /api/hosts
POST /api/hosts/select
POST /api/hosts/:id/connect
POST /api/hosts/:id/disconnect

Tasks

GET    /api/tasks
POST   /api/tasks
PUT    /api/tasks/:id
DELETE /api/tasks/:id
POST   /api/tasks/:id/status
POST   /api/tasks/:id/approval
PUT    /api/tasks/:id/tags

Schedules

GET    /api/schedules
POST   /api/schedules
DELETE /api/schedules/:id

Analytics

GET /api/analytics?days=30

Production Bundle

To prepare a ready-to-run user build without the full repository:

npm run build
npm run package:release

This creates dist/agentspan/ with:

• modular server source
• prebuilt UI assets
• workspace package sources
• agentspan-control.sh
• start-agentspan.sh
• start-agentspan.bat
• release.json
• a short README.txt

For users, the main public path should still be npx agentspan onboard --yes. The release bundle is the portable/offline alternative.

Publishing

The public quickstart is designed around:

npx agentspan onboard --yes

Existing installs should upgrade with:

npx agentspan update

Before publishing a new version:

npm run core:typecheck
npm run core:test
npm run package:release
npm pack --dry-run

Project Structure

agentspan/
├── apps/
├── app/              # legacy Next.js UI (archived)
├── packages/
├── src/              # legacy server runtime (archived)
├── scripts/
└── docs/

License

MIT — see LICENSE