Integration Guide

Holon exposes an HTTP control plane for programmatic access. Start the server with holon serve and interact with agents, tasks, and work items through a REST-style API.

Starting the Server

# Local-only access
holon serve --port 8787

# With token-based authentication
holon serve --port 8787 --token "your-secret-token"

Access modes: local, tunnel, lan, tailnet.

API Conventions

Base URL: http://localhost:8787
Content-Type: application/json
Authentication: Bearer token in Authorization header (when --token is set)

Core Endpoints

Agent Management

Method	Path	Description
`GET`	`/agents/list`	List active agent entries with metadata
`POST`	`/control/agents/:agent_id/create`	Create a new agent
`GET`	`/agents/:agent_id/status`	Get agent status and lifecycle
`GET`	`/agents/:agent_id/state`	Get full agent state snapshot

Messaging

Method	Path	Description
`POST`	`/agents/:agent_id/enqueue`	Enqueue a message into an agent
`POST`	`/control/agents/:agent_id/prompt`	Send an operator prompt
`POST`	`/control/agents/:agent_id/wake`	Wake a sleeping agent
`POST`	`/control/agents/:agent_id/control`	Send a control instruction

Tasks & Work Items

Method	Path	Description
`POST`	`/control/agents/:agent_id/tasks`	Create a command task
`POST`	`/control/agents/:agent_id/work-items`	Create a work item
`POST`	`/control/agents/:agent_id/work-items/:work_item_id/pick`	Pick the current work item
`PATCH`	`/control/agents/:agent_id/work-items/:work_item_id`	Update a work item
`POST`	`/control/agents/:agent_id/work-items/:work_item_id/complete`	Complete a work item
`GET`	`/agents/:agent_id/tasks`	List agent tasks
`GET`	`/agents/:agent_id/briefs`	Get recent briefs/context
`GET`	`/agents/:agent_id/transcript`	Get agent transcript
`GET`	`/agents/:agent_id/events`	Get agent event stream

Workspace & Skills

Method	Path	Description
`POST`	`/control/agents/:agent_id/workspace/attach`	Attach a workspace
`POST`	`/control/agents/:agent_id/workspace/detach`	Detach workspace
`GET`	`/agents/:agent_id/skills`	List agent skills
`POST`	`/control/agents/:agent_id/skills/install`	Install a skill

Callbacks & Webhooks

Method	Path	Description
`POST`	`/callbacks/enqueue/:callback_token`	External callback with payload
`POST`	`/callbacks/wake/:callback_token`	External wake trigger
`POST`	`/webhooks/generic/:agent_id`	Generic webhook ingress

Runtime Control

Method	Path	Description
`GET`	`/control/runtime/status`	Runtime health status
`POST`	`/control/runtime/shutdown`	Graceful shutdown

Examples

Send a message to an agent

curl -X POST http://localhost:8787/agents/my-agent/enqueue \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Review the latest changes in src/",
    "priority": "normal",
    "origin": {
      "kind": "operator",
      "actor_id": "my-service"
    }
  }'

Response:

{
  "ok": true,
  "agent_id": "my-agent",
  "message_id": "msg_abc123"
}

Create an agent

curl -X POST http://localhost:8787/control/agents/reviewer/create \
  -H "Content-Type: application/json" \
  -d '{"template": null}'

Check agent status

curl http://localhost:8787/agents/my-agent/status

Create a work item

curl -X POST http://localhost:8787/control/agents/my-agent/work-items \
  -H "Content-Type: application/json" \
  -d '{"objective": "Review and fix all clippy warnings"}'

Update and complete a work item

curl -X PATCH http://localhost:8787/control/agents/my-agent/work-items/work_123 \
  -H "Content-Type: application/json" \
  -d '{
    "plan_status": "ready",
    "todo_list": [
      { "text": "Run cargo check", "state": "completed" }
    ],
    "blocked_by": "waiting for CI",
    "recheck_after": 600000
  }'

curl -X POST http://localhost:8787/control/agents/my-agent/work-items/work_123/complete \
  -H "Content-Type: application/json" \
  -d '{}'

Create and cancel a timer

curl -X POST http://localhost:8787/control/agents/my-agent/timers \
  -H "Content-Type: application/json" \
  -d '{"duration_ms": 60000, "summary": "reminder"}'

curl -X POST http://localhost:8787/control/agents/my-agent/timers/timer_123/cancel \
  -H "Content-Type: application/json" \
  -d '{}'

Wake a sleeping agent

curl -X POST http://localhost:8787/control/agents/my-agent/wake \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "CI build completed",
    "source": "github-actions"
  }'

List agent tasks

curl http://localhost:8787/agents/my-agent/tasks

Get agent transcript

curl "http://localhost:8787/agents/my-agent/transcript?limit=50"

Trust & Provenance

Every inbound message carries an origin that classifies its source. The runtime uses this to enforce trust boundaries:

operator — Human operator via trusted channel
channel — External integration channel
webhook — Third-party webhook
timer — Scheduled timer trigger
system — Internal runtime subsystem
task — Child task completion

Messages also carry priority (interject, next, normal, background) and trust level metadata.

Operator Transport Bindings

For persistent integration channels, register an operator transport binding:

curl -X POST http://localhost:8787/control/agents/my-agent/operator-bindings \
  -H "Content-Type: application/json" \
  -d '{
    "transport": "http_callback",
    "operator_actor_id": "slack-bot-01",
    "default_route_id": "slack-channel-general",
    "delivery_callback_url": "https://my-service.example.com/holon-delivery",
    "delivery_auth": {
      "kind": "bearer_token",
      "token": "my-delivery-token"
    },
    "capabilities": {
      "supports_interject": true,
      "supports_rich_text": true
    }
  }'

Once bound, use the operator ingress endpoint to relay messages:

curl -X POST http://localhost:8787/control/agents/my-agent/operator-ingress \
  -H "Content-Type: application/json" \
  -d '{
    "text": "User asked: can you explain the build error?",
    "actor_id": "slack-bot-01",
    "binding_id": "binding-abc"
  }'