# Rivetplane

Rivetplane provides REST, WebSocket, SSE, and MCP access to local agent harness sessions. Build or bring an ACP-compatible harness and give it one common control surface. Local runners make outbound connections; the server never connects inbound to a developer machine.

## Documentation
- Human API guide: https://rivetplane.com/docs
- OpenAPI 3.1: https://rivetplane.com/openapi.json
- MCP endpoint: https://rivetplane.com/mcp

## Authentication
Browser signup and login use Supabase Auth. API, MCP, event-stream, and runner access uses control-plane bearer tokens that are stored only as hashes.
Use: Authorization: Bearer <API_TOKEN>
Create an API token in the signed-in dashboard. Machine pairing tokens are scoped to one runner. API tokens are scoped to their account and read/write permissions.

## Session IDs
Remote IDs are namespaced: {machine_id}/{harness_type}/{local_session_id}. Percent-encode the complete ID in REST paths and in session transcript resource URIs.

## REST
- GET /v1/machines
- POST /v1/machines/{machine_id}/retire
- GET /v1/harness-capabilities?machine={machine_id}
- GET /v1/machines/{machine_id}/harnesses/{harness}/capabilities
- POST /v1/machines/{machine_id}/harnesses/{harness}/sessions
- GET /v1/sessions?machine=&harness=&status=&cwd=
- GET /v1/sessions/{session_id}
- GET /v1/sessions/{session_id}/transcript?cursor=&since=&limit=
- GET /v1/sessions/{session_id}/transcript/stream (SSE)
- GET /v1/sessions/{session_id}/pending
- POST /v1/sessions/{session_id}/messages {"text":"..."}
- POST /v1/sessions/{session_id}/pending/respond {"pending_id":"...","response":"approve|deny|free text","scope":"once|always_this_tool|always_session"}
- POST /v1/sessions/{session_id}/interrupt
- POST /v1/billing/webhook (Stripe-signed hosted billing events)
- WS /v1/events/stream with the bearer token in the Authorization header or bearer.<base64url-token> WebSocket subprotocol.

## Creating sessions
First read harness capabilities. Select only a reported directory and model. Send:
{"cwd":"/workspace/project","title":"Research","model":{"provider_id":"peakflo","model_id":"Deepseek v4 Flash"}}
The server rejects unreported directories or models. A 202 response means the command was accepted by the control plane, not that the harness turn completed.
An interrupt can be a no-op when the session is already idle. In that case, no transcript event is added.

## MCP tools
list_sessions, get_session, get_transcript, send_message, get_pending, respond_to_pending, interrupt_session, list_machines, list_harness_capabilities, create_session.
Resource template: session://{percent-encoded-session-id}/transcript

## Safety and errors
- 401: missing or invalid bearer token.
- 403: token cannot access the account, machine, or session.
- 404: resource not found.
- 409: runner offline, no pending interaction, or stale pending_id.
- Always fetch the current pending interaction and respond with its exact pending_id. Never approve "whatever is pending."
- The harness permission system remains authoritative. The control plane relays decisions; it does not bypass permissions.