Getting Started

Quickstart

This guide gets you running Clasper Core (governance) plus the built-in runtime adapter (optional) against a Control Plane-compatible backend.

OpenClaw users: For the fastest path to governing OpenClaw tool execution, see OpenClaw Governance Quickstart. Clasper intercepts OpenClaw tool calls and enforces policy before execution.

Prerequisites

• Node.js 20+
• An LLM API key (OpenAI/Anthropic/Gemini/etc.)

---

Step 1: Install Clasper Core

git clone <repo-url>
cd clasper-core
npm install
cp .env.example .env

---

Step 2: Set up a Control Plane backend

Clasper Core is stateless — it needs a backend to store tasks, messages, and documents. Choose one option:

Option A: Reference Implementation (for testing)

Run the in-memory reference backend from the clasper-core repo:

export AGENT_JWT_SECRET=dev-secret-change-me
export MC_LITE_PORT=9001
npx tsx examples/mission-control-lite/server.ts

This starts a backend at http://localhost:9001 with all required endpoints. Set BACKEND_URL=http://localhost:9001 in your Clasper Core .env.

Option B: Use an Existing Backend

If you have a Mission Control-compatible backend, configure Clasper Core to point to it:

# In .env
BACKEND_URL=http://localhost:8000
AGENT_JWT_SECRET=<same-secret-as-backend>

See Integration for detailed integration patterns.

Option C: Build Your Own Backend

Your backend must implement these endpoints:

Endpoint	Method	Purpose
/api/mission-control/capabilities	GET	Feature discovery
/api/mission-control/tasks	GET	List tasks for user
/api/mission-control/tasks	POST	Create a task
/api/mission-control/messages	POST	Post a message
/api/mission-control/documents	POST	Create a document

Requirements:

1. Shared secret — Clasper Core and your backend must share the same AGENT_JWT_SECRET
2. Agent token auth — Accept X-Agent-Token header with JWT containing type, user_id, agent_role
3. Tenant isolation — Scope all reads/writes by user_id from the token
4. Idempotency — Create endpoints must accept idempotency_key

Validate your implementation:

# Conformance tests the backend directly (use same URL as BACKEND_URL)
export CONTROL_PLANE_URL=http://localhost:9001
export AGENT_TOKEN=<your-agent-jwt>
npm run conformance

See Control Plane Contract for the full specification.

---

Step 3: Create a Workspace

The workspace defines your agent’s personality and behavior:

mkdir -p workspace/souls workspace/skills

Required: workspace/AGENTS.md — Operating rules:

# Operating Rules

- Be helpful and accurate
- Keep responses concise
- Ask for clarification when needed

Required: workspace/SOUL.md — Agent persona (or souls/<role>.md for multi-agent):

# Agent Persona

You are a helpful assistant.

## Communication style
- Direct and clear
- Evidence-based answers

Optional files:

• IDENTITY.md — Branding (name, tagline)
• HEARTBEAT.md — Checklist for autonomous health checks
• skills/<name>/SKILL.md — Skill definitions for tool use

See Workspace Configuration for the full specification.

---

Step 4: Configure Environment

Edit .env:

# Backend connection
BACKEND_URL=http://localhost:9001   # or your backend URL
AGENT_JWT_SECRET=dev-secret-change-me

# Adapter authentication (only required for external execution adapters)
ADAPTER_JWT_SECRET=dev-adapter-secret-change-me

# Async approvals (required for decision tokens)
CLASPER_DECISION_TOKEN_SECRET=dev-decision-secret-change-me

# Exports (optional signing; default off)
CLASPER_EXPORT_SIGNING_MODE=off

# LLM provider
OPENAI_API_KEY=sk-...

# Workspace path (default: ./workspace)
CLASPER_WORKSPACE=./workspace

# Optional: auto-create task with this title
CLASPER_DEFAULT_TASK=My Agent Thread

---

Step 5: Start Clasper Core

npm run dev

Clasper Core starts at http://localhost:8081 (default).

Verify it’s running:

curl http://localhost:8081/health
# {"status":"ok"}

---

Step 6: Send Your First Message

curl -X POST http://localhost:8081/api/agents/send \
  -H "Content-Type: application/json" \
  -H "X-Agent-Daemon-Key: <your-daemon-key-if-configured>" \
  -d '{
    "user_id": "user-123",
    "session_key": "user:user-123:jarvis",
    "message": "Hello, what can you help me with?"
  }'

On success you’ll receive an execution_id and a trace_id you can inspect in Ops and APIs.

---

Common Commands

# Development server
npm run dev

# Production build
npm run build && npm start

# Run dispatcher (delivers notifications from backend to daemon)
npm run dispatcher

# Run heartbeat check
USER_ID=user-123 AGENT_ROLE=default npm run heartbeat

# Run conformance tests against your backend
npm run conformance

# Run unit tests
npm test

---

Docker

cp .env.example .env
# Edit .env with your settings
docker compose up --build

---

Ops Console (Optional)

The Operations Console at /ops provides trace viewing, decision replay (context), simulation, governance health, agent inventory, incidents, and policy testing. Authentication options:

Simple (local dev): Set OPS_LOCAL_API_KEY and use X-Ops-Api-Key: <key> header.

OIDC (production):

OPS_OIDC_ISSUER=https://your-idp.com
OPS_OIDC_AUDIENCE=clasper-ops
OPS_OIDC_JWKS_URL=https://your-idp.com/.well-known/jwks.json
OPS_RBAC_CLAIM=roles

See Governance for RBAC configuration.

---

Optional (but recommended): Try a verifiable export

Once you have traces, you can export evidence for audit and offline verification:

npx clasper-core export --base-url http://localhost:8081 --ops-api-key <key> --tenant-id <tenant> --out ./clasper-export.tar.gz

Verification tooling for exported bundles is in development.

---

Next Steps

Document	Description
Runtime Adapter	Using the built-in runtime (request format, config, flow)
Architecture	Core vs adapters, decision/ingest flows
Integration	Backend + adapter integration patterns
Adapter Contract	External adapter auth + ingest
API Reference	Full endpoint documentation
Operations	Tracing, decision replay/diff, promotions/rollback
Governance	RBAC, budgets, overrides, audit
Configuration	Env vars + rollout toggles
OpenClaw Governance Quickstart	Govern OpenClaw tool execution (policies + local approvals)