Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Skip to content

Control Surfaces

This page defines the user-facing control surfaces for Toolang:

  • the CLI
  • the known-agent registry
  • the per-agent HTTP API
  • the shared bus HTTP API

CLI surface

Top-level command groups:

  • agent lifecycle
    • new
    • clone
    • remove
    • list
  • state materialization
    • sync
  • execution
    • invoke
    • run
    • start
  • capability management
    • skill
    • service
    • prompt
    • psyche
  • shared bus
    • bus serve

Hidden helper commands:

  • home
  • source
  • room
  • init

Rules:

  • all execution commands accept an agent selector
  • invoke is caller-driven one-shot foreground execution
  • run runs the server loop in the foreground and may enable extra loops
  • start launches the selected runtime-loop set in the background

Known-agent registry

Toolang stores global registry state in:

  • ${TOOLANG_ROOT}/agents.db

Logical tables:

  • agents
  • running_agents

Known-agent fields include:

  • agent_uri
  • agent_id
  • agent_name
  • agent_home
  • source_file
  • updated_at

Running-agent fields include:

  • agent_uri
  • pid
  • status
  • sandbox
  • started_at
  • heartbeat_at
  • endpoint

Shared event projection

Toolang stores shared bus projection state in:

  • ${TOOLANG_ROOT}/bus/events.db

This database is:

  • written directly by local agent processes
  • readable even when no standalone bus server is running
  • a projection, not the only execution truth

Core event families:

  • agent_started
  • agent_stopped
  • agent_updated
  • run_started
  • run_finished
  • run_failed

Agent API

Each started agent exposes a local HTTP API.

Endpoints:

  • GET /healthz
  • GET /api/v1/health
  • GET /api/v1/agent
  • GET /api/v1/profile
  • GET /api/v1/runtime
  • GET /api/v1/caps
  • GET /api/v1/tasks
  • PUT /api/v1/tasks/{task_id}
  • PATCH /api/v1/tasks/{task_id}
  • GET /api/v1/chores
  • GET /api/v1/will
  • POST /api/v1/chat
  • POST /api/v1/chat/stream
  • GET /api/v1/chats
  • GET /api/v1/chats/{thread_id}
  • GET /api/v1/runs
  • GET /api/v1/runs/{run_id}
  • GET /api/v1/events
  • GET /api/v1/events/stream
  • POST /api/v1/runs

Bus API

Toolang also exposes a root-level HTTP API over bus/events.db.

Endpoints:

  • GET /healthz
  • GET /api/v1/agents
  • GET /api/v1/agents/{agent_id}
  • POST /api/v1/agents/{agent_id}/chat
  • POST /api/v1/agents/{agent_id}/chat/stream
  • GET /api/v1/runs
  • GET /api/v1/events
  • GET /api/v1/agents/{agent_id}/events
  • GET /api/v1/events/stream
  • GET /api/v1/agents/{agent_id}/events/stream

Responsibilities:

  • list known and active agents
  • list global or per-agent runs and events
  • proxy chat requests to active agent endpoints
  • provide one local endpoint for multi-agent UI integration

Read next

© 2026 Toolang