VOXApiServer

File: vox/api_server.py (class VOXAPIServer)

HTTP interface over the VOX runtime, served on port 8000 by default. Provides fleet management, agent introspection, and capability monitoring without requiring direct access to the Python runtime.

Middleware

• Auth — if VOX_API_TOKEN is set, every request must present Authorization: Bearer <token>; otherwise 401. When no token is set, the server refuses to bind to a non-loopback host.
• Guardrail — POST bodies are run through the inbound InputSanitizer; blocked payloads return 400.

Endpoints

Method	Endpoint	Purpose
GET	/	System info, capabilities, agent tree
GET	/fleet	System info + hierarchy
GET	/agents	Agent tree + hierarchy map
GET	/agents/{id}	Single agent by UUID or name (via _resolve_agent)
GET	/agents/{id}/commands	Agent's command map (get_command_map())
GET	/capabilities	Registry status
POST	/agents/{id}/pause	Pause an active agent
POST	/agents/{id}/resume	Resume a paused agent
POST	/agents/{id}/stop	Stop an agent
POST	/agents/{id}/start	Start an inactive agent
POST	/agents/{id}/restart	Restart an agent

Every route (except /) is registered with and without a trailing slash.

Agent Lookup

All {id} parameters support both UUID and case-insensitive name lookup. The server calls orchestrator._resolve_agent(identifier) which returns the VOXAgent object, then calls agent.describe() to produce the response.

The agent tree (GET /, GET /agents) only includes root agents (those with an empty master_id). To find any agent in the fleet, navigate the tree from its root ancestor through the subordinates chain, or hit GET /agents/{id} directly.

Fleet Snapshot (GET /)

{
  "system": {
    "version": "VOX+1.0",
    "speaker_profile": true
  },
  "capabilities": [
    { "id": "ai.llm", "healthy": true, "loaded": true }
  ],
  "agents": [
    {
      "id": "<root_uuid>",
      "name": "<agent>",
      "state": "ACTIVE",
      "master_id": "",
      "autostart": true,
      "health": true,
      "degraded": false,
      "capabilities": ["comm.gateway"],
      "commands": ["..."],
      "events": ["on_boot"],
      "subordinates": []
    }
  ]
}

Responses

Code	Meaning
200	Success with body
400	Failed lifecycle operation or guardrail-blocked POST
401	Missing/invalid bearer token
404	Agent not found