Skip to main content

REST API (agent)

The agent exposes a local REST API for same-machine clients (plugins, the CLI when talking to a local agent, your own scripts).

What you'll learn​

  • Base URL + port
  • Auth
  • Profile-prefixed routing
  • Key endpoint groups

Base URL​

http://localhost:3005

The default port is 3005. If 3005 is in use, the agent picks the next free port at startup. Override via PORT=<n> env var or -p <n> CLI flag.

To discover the running agent's port programmatically:

vibe status

Auth​

All endpoints (except a few exempt routes) require:

x-agent-api-key: <agentApiKey>

The agentApiKey is generated on first agent run and stored at ~/.boff/vibecontrols/agents/<id>/config.json. Fetch it via:

cat ~/.boff/vibecontrols/agents/<id>/config.json | jq -r .agentApiKey

Or rotate it:

vibecontrols agents rotate-api-key <agent-id>

Profile-prefixed routes​

A single agent process can host multiple profiles ("default", "alpha", "prod") — each connecting to a different backend. All non-exempt routes are prefixed by profile:

GET /api/profiles/default/agent/identity
GET /api/profiles/alpha/sessions

Bare /api/<rest> returns 410 Gone. Clients must first discover active profiles:

GET /api/profiles

Exempt routes (no profile prefix)​

GET  /health                          process liveness probe
GET  /api/profiles                    list active profiles
GET  /api/profiles/:name              profile metadata
GET  /ui/                             web UI bridges
WS   /ws/                             WebSocket
WS   /terminal/                       terminal WebSocket
GET  /code-server/                    code-server proxy (if enabled)

Route groups (under /api/profiles/<name>/)​

GroupWhat
tmux/*Terminal session management (create, send-command, capture-output, etc.)
ssh/*SSH connection management
tunnel/*Per-port tunnel CRUD
agent-tunnel/*Agent's own control-plane tunnel
port-forward/*Local-to-remote / remote-to-local / SOCKS forwards
tasks/*Background task tracking
config/*Configuration + system info
notifications/*Notifications
files/*File operations on the agent's filesystem
git/*Git repository scanning
bookmarks/*Command bookmarks
projects/*Project / repo scanning
ai/toolsAI tool detection (opencode, claude-code, gemini-cli, cursor)
ai/prompts/*Prompt template CRUD (via AI plugin)
agent/identityAgent's identity metadata
agent/gateway-authReceive OAuth credentials from the platform
agent/heartbeatHeartbeat / health

Total: 112+ endpoints across route groups. OpenAPI spec at http://localhost:3005/api/profiles/<profile>/openapi.json when running.

Next steps​