WebSocket API

The product API is one socket: ws://localhost:8000/ws (override with NEXT_PUBLIC_PORTO_WS_URL). Every client frame is JSON with a type. The server replies with JSON (type plus payload). Include trace_id if you want it echoed on errors.

v1 is single-user. The socket is not a public multi-tenant API. Treat it as a local control plane for your own stack.

Connect

const ws = new WebSocket("ws://localhost:8000/ws");
ws.onmessage = (ev) => console.log(JSON.parse(ev.data));

On drop, reconnect and send resume_from with the last seq you saw. The server replays the missed tail or answers reset.

Minimum loop to talk

Open a project

After you create one in the UI (or already have an id):

{ "type": "open_project", "project_id": "<uuid>" }

Connect a provider (cloud / local)

{
  "type": "set_credential",
  "provider": "ollama",
  "api_key": "",
  "base_url": "http://127.0.0.1:11434/v1"
}

Success: { "type": "credential_set", "provider": "ollama", "auth_type": "api_key" }.provider values: claude, openai, gemini, deepseek, xai, openrouter, ollama, local, mistral, mistral_vibe. CLI harnesses (claude_code, codex, grok) do not take a key here.For local, you may also send nickname and instance_id (omit instance_id to add a new row).

List live models (optional)

{ "type": "list_provider_models", "provider": "ollama" }

Reply: { "type": "provider_models", "provider": "ollama", "models": [ … ] }.

Add an agent

{
  "type": "add_agent",
  "room_id": "<room-uuid>",
  "provider": "ollama",
  "name": "Ollama",
  "model": "qwen3:30b-a3b"
}

Success: { "type": "agent_added", "agent_id": "…", "handle": "ollama", "room_id": "…" }.

Chat

{
  "type": "chat",
  "room_id": "<room-uuid>",
  "content": "@ollama ping"
}

The broker streams turn deltas, then a completion event. Cancel with cancel_chat. Emergency halt: emergency_stop.

Credential messages

Client `type`	Success `type`	Notes
`set_credential`	`credential_set`	Validates, then stores. Empty Ollama key becomes `"ollama"`.
`list_credentials`	`credentials_list`	Status only. Never the secret.
`delete_credential`	`credential_deleted`
`list_provider_models`	`provider_models`	Ollama `/api/tags` or OpenAI-compat `/v1/models`.

Agent messages

Client `type`	Success `type`
`add_agent`	`agent_added`
`list_agents`	`agents_list` (name may vary; the UI uses the list handler)
`update_agent`	updated agent payload
`remove_agent`	removed ack
`set_agent_grants`	grants updated

Useful add_agent fields (all optional except room_id + provider):

string

Display name. Empty → provider label.

string

Pin. Omit for the provider default.

string

Role string. Shapes default grants and charter.

string

Local / network host already saved in Settings.

string

Which Local / network row to use.

string[]

["file_ops","web"], ["*"], or [].

Errors

Handler failures return:

{ "type": "error", "code": "…", "detail": "…", "trace_id": "…" }

Unknown type is a structured error, not a socket close. The connection stays open.

What this is not

There is no public REST CRUD for agents. The Next app is the supported client. Use this page when you are scripting a local smoke test or debugging with a raw socket.

​Connect

​Minimum loop to talk

​Credential messages

​Agent messages

​Errors

​What this is not

Connect

Minimum loop to talk

Credential messages

Agent messages

Errors

What this is not