Automate Holon over HTTP

Holon's HTTP control plane lets a script or service drive agents, tasks, and work items without the TUI. This guide starts the server, authenticates, and walks one request through to a result. Every route is served under /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. The default listen address is 127.0.0.1:7878. A non-loopback listen address, or lan/tailnet access, requires a token.

API Conventions

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

The full endpoint list — methods, payloads, and auth requirements — lives in the HTTP control plane reference. Find your route there, then come back here for the workflow.

Examples

Send a message to an agent

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

The public enqueue route accepts only channel or webhook origins, and rejects interject priority. To send a message that carries operator trust, register an operator transport binding instead (see below).

Response:

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

Create an agent

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

Check agent status

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

Create a work item

curl -X POST http://localhost:8787/api/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/api/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/api/control/agents/my-agent/work-items/work_123/complete \
  -H "Content-Type: application/json" \
  -d '{"report_text": "Build fixed and all checks passed."}'

Create and cancel a timer

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

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

Wake a sleeping agent

curl -X POST http://localhost:8787/api/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/api/agents/my-agent/tasks

Get agent transcript

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

Every request carries an origin and a trust level, and the runtime keeps them apart. How those classifications work is in Trust boundaries.

Advanced operator-side controls, including transport bindings, are collected in the HTTP control plane reference.