Agent Management

Lobu exposes a settings API at /api/v1/agents for managing agents at runtime. Both the admin page and CLI commands use this API.

Agent lifecycle

Create an agent

Agents are created via lobu.config.ts (with lobu apply) or the API (at runtime):

# Via API
curl -X POST http://localhost:8787/api/v1/agents \
  -H "Authorization: Bearer $LOBU_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "agentId": "support", "name": "Support Agent" }'

Returns the agent ID and a settings URL for configuration.

List agents

curl http://localhost:8787/api/v1/agents \
  -H "Authorization: Bearer $LOBU_API_TOKEN"

Returns all agents with their name, description, channel count, and last activity.

Update an agent

curl -X PATCH http://localhost:8787/api/v1/agents/support \
  -H "Authorization: Bearer $LOBU_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Customer Support", "description": "Handles billing and account questions" }'

Delete an agent

curl -X DELETE http://localhost:8787/api/v1/agents/support \
  -H "Authorization: Bearer $LOBU_API_TOKEN"

Unbinds all platform channels and removes the agent configuration.

Agent configuration

Fetch the full configuration for an agent:

curl http://localhost:8787/api/v1/agents/support/config \
  -H "Authorization: Bearer $LOBU_API_TOKEN"

This returns everything about the agent:

Section	What it contains
providers	Installed providers, connection status, model preferences, available catalog
instructions	Identity, soul, and user prompts (the IDENTITY.md / SOUL.md / USER.md content)
skills	Enabled skills with metadata, MCP server status
tools	Nix packages, domain grants
settings	Verbose logging, memory enabled

Each section includes source (local, inherited, or mixed) and editable flags so the UI knows what can be changed.

When a new platform channel is bound to an agent, the agent that owns the connection handles it — a channel-triggered automation routes incoming messages. There is no template-agent settings inheritance; each agent’s effective settings come from lobu.config.ts plus its own runtime overrides.

Provider management

Add a provider via API key

curl -X POST http://localhost:8787/api/v1/auth/openai/save-key \
  -H "Authorization: Bearer $LOBU_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "agentId": "support", "apiKey": "sk-..." }'

Provider auth is per provider kind via the /api/v1/auth/:provider/save-key and /api/v1/auth/:provider/logout endpoints. OAuth-granted providers are authorized through the admin UI rather than a device-code REST flow.

Remove a provider

curl -X POST http://localhost:8787/api/v1/auth/openai/logout \
  -H "Authorization: Bearer $LOBU_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "agentId": "support" }'

Browse available providers

curl "http://localhost:8787/api/my-org/installed/agents/support/installed?kinds=providers" \
  -H "Authorization: Bearer $LOBU_API_TOKEN"

Returns installed provider modules for the agent (from the unified catalog installed overlay).

Session history

Check agent status, view messages, and get session stats:

# Is the agent online?
curl http://localhost:8787/api/v1/agents/support/history/status \
  -H "Authorization: Bearer $LOBU_API_TOKEN"

# Get recent messages (paginated)
curl http://localhost:8787/api/v1/agents/support/history/session/messages \
  -H "Authorization: Bearer $LOBU_API_TOKEN"

# Session statistics (message counts, token usage)
curl http://localhost:8787/api/v1/agents/support/history/session/stats \
  -H "Authorization: Bearer $LOBU_API_TOKEN"

Channel bindings

There is no dedicated channels listing endpoint. Platform bindings are managed through connections in the /agents admin UI, and inbound traffic per agent is inspected through the history routes above.

Platform connections

Platform connections (Telegram, Slack, Discord, WhatsApp, Teams bots) are declared in lobu.config.ts with defineConnection and reconciled by lobu apply, and can also be managed from the /agents admin UI. Each connection has a typed config schema (bot token for Telegram, signing secret + bot token for Slack, etc.). There is no /api/v1/connections CRUD endpoint.

Interactive API reference

All endpoints are documented in the OpenAPI spec at /api/docs on your running gateway. Browse it for request/response schemas and try requests directly.