Skip to content

lokustd HTTP API

The lokustd daemon runs a local HTTP server for session management. Default bind: 127.0.0.1:7700 (override with LOKUST_PORT).

All bodies are JSON. CORS headers are permissive — the API is intended for localhost clients only. Bind to a public interface at your own risk.

Health

GET /health

Liveness check.

Response 200 OK 

{ "status": "ok" }

Sessions

GET /sessions

List all sessions, sorted by creation time descending.

Response 200 OK 

[
  {
    "id": "a3f8b2c1-6d4e-4086-b936-233f5b97e959",
    "status": "completed",
    "phases_completed": 5,
    "phases_total": 5,
    "total_tokens": 49793,
    "created_by": "user",
    "project_dir": null
  }
]

POST /sessions

Create a new session using the default 5-agent workflow (architect, security, integration, testing, documentation).

Response 200 OK — the full StoredSession.

POST /sessions/workflow

Create a session from a custom workflow definition.

Request body 

{
  "name": "iPad Streaming Portal",
  "description": "5-agent technical blueprint",
  "agents": [
    {
      "id": "platform-architect",
      "name": "Platform Architect",
      "system_prompt": "You are a senior platform architect...",
      "task_prompt": "Design the end-to-end architecture..."
    },
    { "...": "..." }
  ]
}

Response 200 OK — the StoredSession. Custom prompts are embedded and replayed on /run.

GET /sessions/{id}

Get full session state including all phase outputs.

Response 200 OK — the full StoredSession.

POST /sessions/{id}/run

Run the next pending phase. Blocks until the Claude API call completes (typical: 30–70 seconds per phase).

Response 200 OK 

{
  "phase_index": 2,
  "agent_id": "integration",
  "name": "Integration Agent",
  "status": "completed",
  "duration_ms": 49613,
  "tokens_used": 9961,
  "output_length": 15722
}

Error response: 

{ "error": "no pending phases" }

Call repeatedly to advance through phases until {"error":"no pending phases"}.

POST /sessions/{id}/pause

Mark the session as paused. Does not stop an in-flight phase; the pause takes effect at the next checkpoint.

Response 200 OK 

{ "status": "paused", "id": "a3f8b2c1-..." }

POST /sessions/{id}/resume

Un-pause. Does not automatically run phases — call /run after.

Response 200 OK 

{ "status": "running" }

GET /sessions/{id}/export

Export the session as a .lok JSON document.

Response 200 OK — pretty-printed JSON. Content-Type is application/json (the server treats .lok as JSON).

POST /sessions/import

Import a session from a .lok document.

Request body — the full .lok document as JSON.

Response 200 OK 

{ "imported": "a3f8b2c1-..." }

The session is persisted to ~/.lokust/sessions/<id-prefix>.lok and appears in /sessions.

Data model

StoredSession

{
  "session": {
    "id": "uuid-v4",
    "status": "idle | running | paused | completed | failed",
    "phases": [ /* Phase[] */ ],
    "current_phase_index": 0,
    "total_duration_ms": 0,
    "total_tokens": 0,
    "created_at_ms": 1776042774000
  },
  "project_dir": "/optional/path",
  "created_by": "operator-username",
  "workflow_name": "optional custom workflow name",
  "agent_prompts": [
    {
      "agent_id": "architect",
      "system_prompt": "...",
      "task_prompt": "..."
    }
  ]
}

Phase

{
  "agent_id": "architect",
  "name": "Architect Agent",
  "status": "queued | running | paused | completed | failed",
  "output": "agent-produced text (may be several KB)",
  "duration_ms": 30052,
  "tokens_used": 1754
}

Persistence

Sessions are persisted to ~/.lokust/sessions/<id-prefix>.lok on every update. Deletes are not yet supported — remove files manually and restart the daemon, or use a DELETE endpoint when available.

On startup, lokustd scans the sessions directory and loads all .lok files it finds.