opendray Third-Party Integration Guide#

This is the canonical, forward-looking contract that every third-party app or website MUST follow to integrate with opendray. opendray is a self-hosted gateway that drives AI coding CLIs (Claude Code, Codex, OpenCode, antigravity) over a PTY behind a unified REST + WebSocket API. A third-party app integrates by being registered by an operator (admin-only), receiving a one-time scoped API key, and then spawning and driving agent sessions over REST while optionally proxying its own UI and subscribing to a live event stream. This document states the rules as explicit MUST / SHOULD / NEVER, documents the current reality honestly (including what is not enforced yet), and gives you a runnable end-to-end path.

Who this is for#

External developers building an app, bot, website, or service that drives opendray agent sessions. You have never seen opendray's internals and you do not need to. You will be given an API key by the opendray operator. This guide tells you exactly what you may send, what you will receive, what is guaranteed, and what you MUST tolerate.

Table of contents#

1. Current reality — read this first
2. The integration model
3. Registration & the API key
4. Authentication on every request
5. Scopes & authorization
6. The unified spawn profile — configuring what runs
7. Driving a session & getting replies
8. Memory & privacy
9. Reverse proxy, event stream & health
10. Observability & call audit
11. Security & safety
12. Operating many integrations (multi-tenancy)
13. Upgrades, restarts & offboarding
14. HTTP status & error-shape reference
15. Data formats
16. Endpoint reference
17. End-to-end worked example
18. Onboarding checklist
19. Scenarios & edge cases (quick reference)
20. DO / DON'T summary
21. Versioning of this guide

1. Current reality — read this first#

Calibrate before reading the deep dives. These are verified properties of the current build (/api/v1, opendray v2.9.0):

• NO rate limiting, quota, or concurrency cap exists. There is no 429, no Retry-After, no per-integration session cap anywhere in the integration or session HTTP paths. An integration can spawn unbounded sessions and exhaust the host. Respecting limits is an operator responsibility (process/OS isolation) and an integrator courtesy (self-throttle). NEVER write client code that expects a 429 or a Retry-After header from opendray today.
• Scope enforcement is partial. Enforced today: event:subscribe:<topic> (event WebSocket), memory:read / memory:write (/memory/*), and providers:write / providers:update (the provider mutation routes). Still declared but not enforced: session:*, channel:*, and provider:read (reading GET /providers is open to any valid key). See §5.
• Pure-API consumers receive session.idle, NOT session.turn_completed. session.turn_completed is only emitted for sessions armed by the channel layer. A REST POST /input does NOT arm turn detection. If your code blocks on session.turn_completed for a pure-API session, it will hang forever. See §7.
• No event replay. If your event WebSocket disconnects, every event published during the gap is lost. There is no catch-up buffer. You MUST reconcile state via REST after reconnect.
• POST /sessions is not idempotent and POST /input is at-least-once. Retrying a timed-out create leaks a session; retrying an input double-sends bytes to the PTY. There is no idempotency key. See §13.
• Permission is permission_mode, not a boolean. The spawn profile's tool-approval policy is the provider-agnostic field permission_mode (default | bypass). It replaced the old bypass_permissions boolean — that key is no longer accepted on the wire (a stray bypass_permissions in a request body is silently ignored). An omitted/empty permission_mode normalizes to "default" (the provider's normal approval flow). See §6.

2. The integration model#

Two patterns#

Every integration is one of two shapes. Pick deliberately.

This document focuses on Pattern A. Pattern B is fully covered in the visayabai bridge guide; the bridge wire protocol is summarized in §17.

The lifecycle#

1. Register (operator, admin-only, one-time) → you receive a one-time odk_live_… key.
2. Configure the spawn profile (operator, on the integration row) → which agent + what MCP / system-prompt / permission_mode to inject.
3. Spawn sessions (your app, per user/conversation) → POST /sessions with the key.
4. Drive (your app) → POST /input, listen on the event WS for session.idle / session.ended, read output, post back.

Isolation: origin=integration#

Every session your integration creates is stamped server-side with origin=integration and your integration_id. These fields are derived from your authenticated principal, NEVER from the request body — you cannot spoof them. This gives three guarantees:

• Visibility isolation. Integration sessions are hidden from the operator's session list. The operator console (admin token, or no integration principal) never sees origin=integration sessions. An integration token sees only sessions whose integration_id matches its own.
• Memory isolation. Integration sessions default to memory_policy=none: nothing is captured into shared memory, and the cross-project memory MCP is never attached. See §8.
• Spawn-profile injection. Your declared MCP servers / system prompt / permission_mode apply only to your sessions, never to operator or CLI-direct sessions.

3. Registration & the API key#

Credential model — who needs admin, who gets a key#

A third-party app NEVER needs, sees, or holds the opendray admin account/password. That is the entire point of the model: there are two distinct credentials for two distinct roles.

So:

• The admin credential is used by the operator, once, to register the app (and later to rotate/disable/delete it). The third party is never given it.
• The third party authenticates only with its own odk_live_… key. That key is independently revocable/rotatable — if it leaks, the operator rotates it without touching the admin token or any other integration.
• The key is not "admin lite": it cannot reach the management endpoints (registering or administering integrations stays admin-only — see the table in §16).

Honest scope-enforcement caveat. Per-route scope enforcement is still only partial (enforced: event:subscribe:*, memory:*, and the provider mutation scopes providers:write / providers:update — see §5). So an integration key can currently reach the business endpoints (POST /sessions, GET /providers, …) regardless of its declared scopes. It still is not the admin credential — it cannot manage integrations and is independently revocable — but until per-route enforcement is complete, treat "which apps the operator chose to register" as the real trust boundary, and grant minimal scopes anyway so your client is correct once enforcement turns on.

Registration is admin-only#

The operator (admin bearer token) registers you. Your app NEVER self-registers. You ask the operator for a key; they create the row and hand you the plaintext out-of-band.

The default memory_policy is none. (An internal code comment says "quarantine" — it is stale and wrong; the registration path sets none.)

Response (201):

Consumer-only integration#

Set both base_url and route_prefix to "". Consumer-only integrations cannot be reverse-proxied, are never health-probed (stay health_status: "unknown"), but can fully drive sessions and subscribe to events. Internally opendray stores a synthetic _consumer_<id> prefix to satisfy a DB constraint; it is blanked in every JSON response, so you always see "route_prefix": "".

The API key#

• Format: odk_live_ + base64url payload (~56 chars total).
• It is shown exactly once, in the registration (or rotation) response's api_key field. opendray stores only a bcrypt hash (cost 12) and discards the plaintext.
• It is NEVER shown again — not in GET /integrations/{id}, not in GET /integrations, not in logs, not in the UI, not in backups.
• It is a first-class Principal, equivalent to an admin bearer for the endpoints it can reach.

You MUST:

• Store the plaintext in a secret manager or encrypted env var (mode 0600), NEVER in source control or logs.
• Treat it like a password; reference it in logs only by integration ID/name.

Rotation, disable, delete (admin-only)#

System integrations (is_system: true, e.g. the opendray-memory MCP bridge) cannot be deleted or rotated by the operator (403 ErrSystemIntegration) — destroying their key would orphan running sessions whose mcp.json references it.

4. Authentication on every request#

Send the key as a bearer token on every request.

HTTP:

WebSocket (browsers can't set custom WS headers — use the query param):

A Bearer header is also accepted on the WS handshake if your client can set it; otherwise use ?token=.

Validation order (combined middleware):

1. Admin bearer (in-memory map, no bcrypt).
2. Integration key fallback: scans all enabled integrations' bcrypt hashes; first match wins. The token → integration_id result is cached in an in-memory map to skip bcrypt on repeat calls.

The token cache is a plain map cleared wholesale on disable / rotate / delete (not a per-entry LRU). On a cache hit, the row is re-read and re-checked for enabled, so a disabled key is rejected even if cached.

On failure: 401 with WWW-Authenticate: Bearer realm="opendray" and body {"error":"unauthorized"}. All invalid keys are treated identically (no existence side-channel).

5. Scopes & authorization#

Principals#

The canonical scope list#

Note the spelling: the (unenforced) read scope is provider:read (singular), while the (enforced) mutation scopes are providers:write / providers:update (plural). They are distinct strings — grant exactly what the code checks.

Wildcards: prefix match only, suffix .*.

• event:subscribe:session.* grants session.idle, session.turn_completed, session.ended, etc.
• event:subscribe:* grants all topics.
• There is no hierarchy: memory:* does NOT expand to memory:read/memory:write — grant each explicitly.

Enforcement reality and what you MUST do#

• Enforced today: event:subscribe:<topic> (event WS), memory:read, memory:write, db:read, db:write, and providers:write / providers:update (the provider mutation routes).
• Declared but unenforced: session:*, channel:*, provider:read. Any valid integration token can call POST /sessions, GET /providers, etc., regardless of declared scopes (deferred — see roadmap in §21).

You MUST:

• Request the minimal scopes you need and document why.
• Design your client so that any endpoint can start returning 403 in a future build (when enforcement lands). Handle 403 gracefully (log, alert operator, do NOT retry-loop).

You MUST NOT:

• Rely on scope enforcement as an access-control boundary for the still-unenforced scopes. The operator is the trust boundary; isolation between mutually-untrusting integrations is achieved at the OS/instance level (see §12).

The 403 body text differs per surface (not one canonical message):

• Event WS: missing scope: event:subscribe:<topic>
• Memory: requires admin or the "memory:read" scope (or memory:write)
• Database tool: requires admin or the "db:read" scope (or db:write)
• Provider mutation: requires admin or the "providers:write" scope (or providers:update)

6. The unified spawn profile — configuring what runs#

The integration row carries one unified spawn profile in two halves on the same row. The whole point: declare intent ONCE, stay decoupled from any single CLI. opendray translates your intent per-provider at spawn time.

Half 1 — Default agent (identity; overridable per-request)#

These are defaults. A POST /sessions request that supplies its own provider_id/model/claude_account_id always wins; an omitted field falls back to the integration default.

Half 2 — Injection (tools/prompt/permission; integration-only)#

The hard rules#

• MUST declare all MCP / system-prompt / permission intent on the integration row, never in POST /sessions args.
• NEVER hand-build per-CLI flags (--mcp-config, --append-system-prompt, --dangerously-skip-permissions, --yolo, …) into the request args. That hard-locks you to one CLI and breaks the moment the operator switches the default provider.
• Injection fields are integration-only and are NOT per-request overridable. CreateRequest has no mcp_servers/system_prompt/permission_mode fields, so any such keys in the request body are silently dropped by the JSON decoder (there is no 400 rejection today). This is by design: an end-user message routed through your bot MUST NOT be able to mutate the tools, prompt, or permission policy of an unattended session.

Precedence#

Identity fields (provider_id, model, claude_account_id):

For model specifically there is a higher layer: a literal --model X in the request args wins over the model field and over the integration default (the manager dedups overridden flags). Prefer the model field; don't fight it with args.

MCP server descriptor#

• name (required): unique; integration entries win on name collision against vault/provider-config entries.
• transport (default stdio): stdio | sse | http.
• command/args for stdio; url/headers for sse/http.
• ${KEY} placeholders in command/args/env/headers are resolved at spawn time from the operator's secrets dotenv file (secretsFile). A missing key passes the literal ${KEY} through so the agent surfaces a clear "credential not set" error rather than failing silently. Secrets live only in memory + the per-session scratch dir; they are NEVER written to the DB or logs. NEVER hardcode credentials — use ${KEY} and tell the operator which keys to add.

Per-provider translation (verified)#

The bypass flag is appended only when permission_mode == "bypass"; default leaves the provider's normal approval flow untouched (and, for codex, leaves the operator's configured approval policy in place). Switching providers requires zero code changes on your side: the operator patches default_provider_id, and the next session renders the same intent through the new CLI's surfaces.

Antigravity specifics: agy loads MCP servers from exactly one file, the HOME-keyed ~/.gemini/config/mcp_config.json. opendray merges your mcp_servers into it non-destructively at spawn (only opendray-managed entries are ever updated or removed; remote descriptors are translated to agy's serverUrl field automatically). Because that file is per-HOME rather than per-session, integration MCP servers are rendered for antigravity only when the spawn is bound to a dedicated antigravity account (accounts get isolated HOMEs) — on an unbound spawn they are dropped with a gateway-side warning, never written into the operator's shared HOME where sibling sessions could read their credentials. If the operator won't bind an account, point the integration at claude (per-session --mcp-config) instead. Even account-bound, two concurrent antigravity sessions under the same account HOME see the union of their injected servers.

permission_mode — the provider-agnostic permission contract#

permission_mode is the live field (a permission_mode TEXT column with two valid values; it replaced the old bypass_permissions BOOLEAN).

• default (the safe default; an empty/omitted value normalizes to this) — the agent runs under the provider's normal tool-approval flow. For an operator-attended TUI this means a human gates tool calls.
• bypass — opendray appends the resolved provider's unattended/auto-approve flag (table above) so the agent runs without a human approving tool calls.

An invalid value is rejected 400 permission_mode must be default|bypass. Set it on the integration row (register or PATCH), never per request, and never hand-build the per-CLI bypass flag into args — that re-locks you to one CLI and bypasses the structural guard in §11.

7. Driving a session & getting replies#

This section overrides any "subscribe to session.turn_completed" advice for Pattern A. Read it before the worked example.

Create a session#

• provider_id and cwd are required (omitting cwd → 400). If provider_id is omitted it is filled from your integration default; if there is no default the create will fail downstream.
• args are raw CLI args. Keep them empty and let your MCP tools carry the work. NEVER put MCP / system-prompt / permission flags here (§6).
• origin and integration_id are stamped server-side from your principal; any values you send are ignored.
• Response 201 with the session (id, state, pid, origin: "integration", integration_id).

Send input#

• data is raw bytes to the PTY stdin. You MUST include the trailing \n ("press enter").
• Control bytes allowed: \x03 = Ctrl-C, \x04 = Ctrl-D.
• Returns 204 No Content (fire-and-forget; asynchronous).
• NOT idempotent in the dedup sense: a retried /input writes the bytes again. NEVER blindly retry an input you believe may have landed.

Getting the reply — the correct signal#

Subscribe to the event WS before sending, and key off the right event:

Three correct strategies for Pattern A — pick one:

1. session.idle — subscribe event:subscribe:session.idle (or session.*), wait for idle matching your session_id, read recent_output. Simple; the idle threshold is operator-configurable (default ~5 minutes for unattended sessions, so tune it down for interactive bots or use strategy 3).
2. Agent-push via your own MCP tool — give the agent a reply_to_user-style MCP tool in your spawn profile and a system prompt that says "reply ONLY via reply_to_user." The tool calls back into your service. This is the most reliable, latency-tight pattern for unattended bots and is what the PDA secretary uses. It does not depend on idle timing.
3. Buffer polling (fallback when you can't hold a WS) — after POST /input, poll GET /sessions/{id}/buffer?since=<cursor> and advance the cursor from the X-OpenDray-Buffer-Cursor response header.

NEVER scrape the PTY buffer in a tight 100ms loop, and NEVER block forever on session.turn_completed for a pure-API session.

Session state machine#

• POST /stop SIGTERMs the process but keeps the row → restartable with POST /start. Returns 200 + session.
• POST /start re-spawns under the original provider/cwd/args/account. For a terminal (ended/stopped) row this is a fresh PTY — prior in-process context is lost (the row/history is preserved). Returns 200 + session. It does not resume a live process.
• DELETE /sessions/{id} SIGTERMs then drops the row. Irreversible.
• Driving an already-ended session returns 409 (ErrAlreadyEnded).

File uploads#

POST /api/v1/sessions/{id}/uploads (multipart). Capped at 16 MiB per request. Returns the saved path under os.TempDir()/opendray-uploads/{session_id}/. Reference it in a message ("analyze the file at /…"). Paths are session-scoped and may be garbage-collected after the session ends; do not share them between sessions. NEVER stream large files into stdin.

8. Memory & privacy#

The policy (integration-scoped, NOT per-request)#

MUST NOT put memory_policy in a POST /sessions body — it is set on the integration row by the operator and applies to all your sessions. MUST NOT try to disable capture by hand-crafting args.

Isolation guarantees (current build)#

• Read-side (verified): the cross-project opendray-memory MCP is not attached to origin=integration sessions. The agent cannot read the operator's or other integrations' memory.
• Write-side (verified): the capture pipeline resolves your policy up front; none → the session is skipped entirely (no history read, no summarizer call). Direct POST /memory/store from an integration key applies the same tier routing: none → 403, full → durable, anything else → quarantine (30-day TTL). Global-scope writes always require admin (403 for integration keys).
• Partitioning is by principal: the integration:<id> memory zone. When a quarantine/full integration's session is captured, the facts are written to a dedicated scope_key = "integration:<integration_id>" zone — not the session's cwd. The KB / git-activity / mirror enumerators are guarded to skip these zones, so a third-party's facts are isolated by principal, regardless of which cwd its sessions use. (This is the behavior shipped in #380; it is no longer cwd-collision-dependent.) Ephemeral cwds (/tmp/*, /var/folders/*/T) are still never captured, regardless of policy.
• You do not need to micro-manage cwd for memory isolation anymore. A distinct stable cwd per integration is still good hygiene (file isolation — see §12), but memory capture no longer leaks across integrations even if two share a cwd. The operator purges your zone with POST /memory/delete-by-scope using scope_key = "integration:<your-id>" (§13).

SHOULD: default to none; escalate to quarantine/full only after the operator vets your data quality and trust. For PII/regulated data, stay none.

The Database tool (/dbtool/*)#

opendray can hold per-project database connections (a JetBrains-style database tool): the operator registers a connection against a project cwd, and agents/integrations browse its schema, read table data, run SQL, and — on writable connections — edit rows. Passwords are encrypted at rest with the same field cipher as channel/git-host secrets and are never returned by any read endpoint (has_password: true instead).

Supported engines: postgres, mysql, mariadb, sqlite (the connection's driver field). MySQL and MariaDB share one implementation and use host/port/username/password like PostgreSQL (a MySQL "schema" is a database). SQLite is a file-path connection: db_name holds the path (no host/port/username), the path is fenced to the connection's project cwd — a path escaping it via ../ or a symlink is rejected at open time — and extension loading is disabled. All engines share the same REST surface, read-only fence and read/write scopes below; only the connection form differs.

Trust model — read before using:

• Registering a connection is admin-only. POST/PATCH/DELETE /dbtool/connections and the test endpoints reject integration keys (requires admin). An integration can never point opendray at a new database host — that is the SSRF-shaped surface, reserved for the operator. You only use connections the operator already approved.
• db:read gates browsing: GET /dbtool/connections?cwd=…, …/schemas, …/tables, …/meta, POST …/table-data, and read-only POST …/query (SELECT/EXPLAIN/SHOW…). Read statements execute inside a server-side READ ONLY transaction with a statement timeout, so a data-modifying CTE fails server-side even if it slips past classification.
• db:write gates mutation: POST …/rows/{insert,update,delete} and write/DDL statements through …/query. A connection the operator marked read_only refuses every write regardless of scope (403 dbtool: connection is read-only). Row edits require the table's full primary key; PK-less tables cannot be edited.
• The auto-attached opendray-dbtool MCP is not given to origin=integration sessions — same isolation rule as memory. Your integration reaches the Database tool through its own scoped key over REST, not through a spawned session's ambient tools, and only for connections registered under a project it is allowed to see.
• Non-admin callers are bound to one project (cwd). Every /dbtool/* call from an integration key MUST carry a ?cwd=<project> query parameter; the gateway rejects a by-id call whose connection belongs to a different project (404) and refuses a connection list with no cwd (403). Admin callers (the operator's web UI) may omit cwd to browse across projects.
• For opendray's own auto-attached MCP, the cwd binding is cryptographic. The opendray-dbtool key is db:signed; per session opendray injects an X-OpenDray-Dbtool-Sig = HMAC(server-secret, cwd) header, and the gateway rejects a signed-key call whose signature doesn't match cwd. So even an agent that extracts the injected key cannot forge another project's cwd. Two exceptions fall back to the plain ?cwd= check: antigravity (its HOME-global MCP config can't carry a per-session signature — a Google limitation), and third-party integration keys you were granted (which are not db:signed). You never compute this header yourself; it applies only to opendray's own injected MCP.

MUST: always pass ?cwd=; request db:read alone unless you genuinely mutate data; handle 403 on write paths as "this connection is read-only or my key lacks db:write", not a retryable error. MUST NOT assume a connection exists — call GET /dbtool/connections?cwd=… first; an empty list means the operator configured no database for that project.

9. Reverse proxy, event stream & health#

These three HTTP surfaces are for Pattern A's optional extras and Pattern B. Consumer-only integrations use only the event WS.

Reverse proxy — /api/v1/proxy/{prefix}/* (admin-only)#

Lets the operator reach your HTTP service through opendray. A request to GET /api/v1/proxy/acme/api/v1/x?p=1 is forwarded to <base_url>/api/v1/x?p=1.

• opendray strips the caller's Authorization header and injects:
  • X-OpenDray-Forwarded-For: <client-ip:port>
  • X-Integration-ID: <integration-id>
  • X-OpenDray-API: v1
• NEVER rely on an inbound Authorization header to identify the caller — it has been removed. Use X-Integration-ID.
• 403/disabled → 503 {"error":"integration disabled"}. health_status == unhealthy → 503 {"error":"integration unhealthy"}. Upstream unreachable/timeout → 502 {"error":"upstream: …"}. base_url that parses at registration but fails at proxy time → 500.

Event WebSocket — /api/v1/integrations/_events#

• topics is a required CSV (missing → 400 topics query param required (CSV); all-blank → 400 no valid topics).
• Admins MAY also connect (the route is wired under the combined middleware). Admins subscribe with no per-topic scope check (per ADR 0009). Integration principals MUST hold event:subscribe:<topic> for every requested topic — if any one is missing the whole subscription is rejected 403 before the upgrade (no partial subscription).
• Frame shape:[object Promise]
• Heartbeat: opendray sends a WS ping every 20s; respond with pong (most libraries auto-pong). Per-frame write deadline is 5s.
• Backpressure = disconnect, NOT silent drop. Each subscriber has a 64-event buffer; if a write fails or exceeds the 5s deadline, opendray tears down the entire connection (it does not drop individual events and keep going). A slow consumer loses the whole stream. You MUST reconnect with exponential backoff and re-subscribe.
• No replay. Events published while you were disconnected are gone. After reconnect, reconcile via GET /sessions/{id}.

Topic families: session.* (idle, turn_completed, ended), integration.* (registered, deregistered, health_changed, key_rotated), channel.*.

Health probes — GET {base_url}/health#

Only integrations with a non-empty base_url are probed (every 30s, 5s timeout; also immediately on registration). Consumer-only integrations are never probed (stay unknown).

Expected response (all fields optional):

status ∈ healthy | degraded | unhealthy. Any 2xx with empty/missing status is treated as healthy.

Transition rules (verified — note the asymmetry):

• Transport error or non-2xx → 1st time degraded, 2nd consecutive unhealthy (consecutive-failure counter).
• Body status:"degraded" → degraded but does NOT touch the failure counter.
• Body status:"unhealthy" → unhealthy (does not touch the counter).
• Any 2xx with healthy/empty status → resets the counter to 0 and sets healthy.
• Unhealthy AUTO-RECOVERS: a single healthy 2xx probe flips you back to healthy regardless of prior state. There is no sticky-unhealthy latch.

When unhealthy, only the reverse proxy returns 503. Your session/event API calls still work. A status change emits integration.health_changed.

SHOULD: implement /health as a millisecond-scale in-memory check (no DB calls). Use degraded under load (proxy stays open) and unhealthy only when truly broken.

10. Observability & call audit#

opendray records integration traffic for the operator. As an integrator, know that:

• Inbound REST calls authenticated as an integration are logged (method, path, status, duration, bytes, request id, integration_id) — not just proxy calls.
• Outbound proxied calls are logged by the proxy handler.

The operator reads this via the admin-only audit endpoint:

Response: {"entries":[…], "next_cursor": "<int>" | null} (keyset pagination: rows have id < cursor; default limit=100).

A per-integration summary endpoint (/integrations/_calls/summary) is a TODO, not yet wired — do not call it.

You SHOULD log integration_id + session_id for every user interaction on your side so support can correlate with the operator's audit.

11. Security & safety#

Injection is one-way and integration-only#

Already stated in §6; restated as a security rule: an end-user message routed through your bot MUST NOT be able to inject MCP servers, rewrite the system prompt, or flip the permission mode. opendray enforces this structurally — those fields don't exist on CreateRequest. You MUST keep it that way: never invent a path that lets request data reach args as per-CLI injection flags.

permission_mode: bypass = you own the safety policy#

When permission_mode: "bypass", every tool call auto-approves with no human at the TUI.

• MUST, if permission_mode: "bypass", validate/sanitize/rate-limit every user input before POST /input. Treat the agent as an unauthenticated executor of whatever it's told.
• If your bot is a pure relay with no policy of its own, set permission_mode: "default" so the operator-attended TUI gates tool calls.
• The cwd is a trust signal, not a sandbox — opendray does not chroot/jail the agent. A tool that runs rm -rf / will run. Real isolation is the operator's job (OS sandboxing, containers, separate instances — see §12).

SSRF via base_url#

opendray does not validate base_url host/range; the proxy will forward to 127.0.0.1:6379, internal APIs, etc. Operators MUST only register integrations whose base_url they trust and SHOULD apply egress controls. Integrators MUST document a stable, controlled base_url so the operator can audit it; never derive it from user input.

Key hygiene#

Store in a secret manager; never commit/log; rotate on a schedule and immediately on suspected leak (ask the operator to rotate-key). In-flight sessions survive rotation (the old key is baked into the running session's config); only new requests need the new key.

12. Operating many integrations (multi-tenancy)#

When one gateway hosts N integrations, integrators and operators MUST understand:

• Shared host UID. All spawned CLIs run as the opendray OS user. cwd is not a security boundary, so integration A can read integration B's files. To isolate mutually-untrusting integrations, run separate opendray instances / containers / VMs or apply OS-level sandboxing. Do not rely on scopes or cwd alone.
• No per-integration quota. Any integration can spawn unbounded sessions (§1). Operators MUST cap resources at the OS/container level; integrators SHOULD self-throttle and reuse sessions per conversation.
• Shared cold-auth cost. Verifying an integration key on a cache miss scans all enabled integrations' bcrypt hashes (O(enabled rows)). Many enabled integrations + many distinct fresh tokens = more bcrypt work. Reuse a single key and let the token cache absorb repeats.
• Shared event bus. Each WS subscriber has a 64-event buffer and is torn down on write stall (§9). A misbehaving subscriber affects only its own connection, but you MUST reconnect on disconnect.
• Memory partitioning is by principal. Capture for a quarantine/full integration lands in its own integration:<id> zone, so memory does not leak across integrations even on a shared cwd (§8). File-level isolation is still cwd/OS-based (the point above) — a distinct cwd remains good hygiene.

13. Upgrades, restarts & offboarding#

What you MUST tolerate across an opendray restart/upgrade#

• API keys survive. Restarting/upgrading the gateway does not change your key.
• Session rows survive; processes may not. On restart, opendray reconciles sessions; a previously-running session may come back running (auto-resume) or land in a non-ended interrupted state. Session IDs survive in the DB.
• Event WS connections do NOT survive and there is no replay. You MUST reconnect with backoff and reconcile state via GET /sessions/{id} after the gateway comes back.
• Treat 5xx / connection-refused as transient. Use a circuit breaker + exponential backoff (e.g. 1s→2s→4s… capped at 60s, with jitter), queue user messages locally, and drain on recovery. There is no 429; backoff is for 503/network only.

Retry safety#

• POST /sessions is not idempotent — a retry after a timeout may leak a second session. Prefer to read back (GET /sessions filtered to your integration) before retrying a create, or accept and reap duplicates.
• POST /input is at-least-once — a retry double-sends bytes. NEVER auto-retry an input that may have landed.
• There is no idempotency-key mechanism.

Offboarding runbook (operator)#

To fully retire an integration:

1. Disable — PATCH /integrations/{id} {"enabled": false} (blocks new auth, clears token cache).
2. Stop orphaned sessions — disabling/deleting does NOT terminate running sessions; DELETE each of the integration's sessions (visible to an admin by id, or while the key is still valid via the integration's own list).
3. Purge captured memory — for quarantine/full integrations, the operator wipes the zone with POST /memory/delete-by-scope (admin-only) for the integration's scope_key = "integration:<id>". none integrations have nothing to purge.
4. Delete the row — DELETE /integrations/{id} (irreversible) — or leave it disabled for the audit trail.

14. HTTP status & error-shape reference#

The error body is uniformly:

There is no 429 and no Retry-After.

15. Data formats#

• Timestamps: all server times are UTC. Event ts is RFC 3339 Nano (2026-06-17T14:32:45.123456789Z). Integration timestamps (created_at, rotated_at, health_last_seen) are UTC. Parse with any standard library.
• ANSI: recent_output and GET /sessions/{id}/buffer contain terminal escape codes. MUST strip them before rendering to a chat/email surface — e.g. re.sub(r'\x1b\[[0-9;]*m', '', text) (Python) or sed 's/\x1b\[[0-9;]*m//g'.
• Buffer cursor: GET /sessions/{id}/buffer?since=<int> takes a byte offset. The response sets X-OpenDray-Buffer-Cursor (next offset to read from) and X-OpenDray-Buffer-Start (the ring-buffer eviction floor — if your since is below it, scrollback was evicted). Use the header values; never hand-compute cursors. Invalid since → 400 invalid since: must be non-negative integer.
• List envelopes (no pagination): GET /integrations → {"integrations":[…]}, GET /sessions → {"sessions":[…]} — full, unbounded lists. GET /sessions/{id}/history?limit=N takes a limit but no offset/cursor. Only /integrations/_calls is paginated (cursor/limit).

16. Endpoint reference#

Base path: https://<host>/api/v1. Auth: Authorization: Bearer odk_live_… (or ?token= on WS). Admin-only rows are marked.

17. End-to-end worked example#

Pattern A (consumer) — register, drive, reply via session.idle#

1. Operator registers (admin, one-time):

2. App drives the loop (Python, reply via session.idle):

Best practice for unattended bots: instead of session.idle, give the agent a reply_to_user MCP tool (in mcp_servers) and force it via the system prompt; the tool calls back into your service directly — tighter latency, no idle-threshold tuning.

3. Operator later switches provider — your code unchanged:

Pattern B (bridge) — wire protocol#

For chat bots, register a kind=bridge channel (operator UI) and connect:

• Register: {"type":"register","platform":"my-bot","capabilities":["text","typing"],"metadata":{}} → {"type":"register_ack","ok":true}.
• Inbound (you→opendray): {"type":"message","conversation_id":"user-123","user_id":"456","user_name":"Alice","text":"hello"}.
• Outbound (opendray→you): {"type":"send","conversation_id":"user-123","text":"…"}.
• conversation_id is the stable routing key; opendray binds each to its own session and handles reply detection for you. Full details: docs/integrations/connecting-visayabai-bot.md.

18. Onboarding checklist#

Pre-launch

• Choose your pattern (A consumer vs B bridge).
• List your MCP tools and decide your reply strategy (session.idle vs agent-push MCP tool).
• Decide memory_policy (default none; escalate only with operator trust).

Registration

• Ask the operator to register you; verify scopes, default provider/model, MCP servers, permission_mode.
• Store the odk_live_… key in a secret manager (never source/logs).
• Smoke test: curl -H "Authorization: Bearer odk_live_…" https://HOST/api/v1/sessions → 200 {"sessions":[]}.

Development

• Create sessions with a name prefix; let integration defaults fill empty fields; keep args empty.
• Open ONE persistent event WS; subscribe session.idle,session.ended; reconnect with backoff; reconcile via REST after reconnect.
• Strip ANSI before rendering.
• Handle session.ended (recreate) and 409 ErrAlreadyEnded.
• Test with Claude AND at least one other provider — verify MCP + system prompt translate.

Deployment

• Rotate the key before go-live; use the fresh token in prod.
• Log integration_id + session_id per user interaction.
• Circuit-breaker + backoff on 503/network; never expect 429.
• Alert on session.ended and on sustained idle latency.

19. Scenarios & edge cases (quick reference)#

20. DO / DON'T summary#

21. Versioning of this guide#

This guide describes the opendray /api/v1 integration contract as of opendray v2.9.0 (2026-06-19). It is verified against the current code in internal/integration, internal/session, internal/catalog, and internal/memory.

• The API path /api/v1 is the stable surface; proxied requests carry X-OpenDray-API: v1. There is no opendray-version discovery endpoint; the version field on an integration is yours, not opendray's.
• Landed since the first cut of this guide (now current, no longer forthcoming): the provider-agnostic permission_mode field replacing the old bypass_permissions boolean (§6); the per-principal integration:<id> memory zone (§8); scope enforcement on the provider mutation routes (providers:write / providers:update, §5); real MCP injection for antigravity sessions via ~/.gemini/config/mcp_config.json (§6 — earlier releases silently dropped mcp_servers on antigravity); and the Database tool with db:read / db:write scopes and admin-only connection registration (§5, §8). Build against permission_mode + memory_policy=none.
• Reserved for the future: the agent_id field (§3) — accepted and stored today but not read at runtime; the eventual home for a named, reusable agent bundle. Leave it empty.
• Roadmap: per-route scope enforcement for the still-unenforced session:* / channel:* / provider:read. Design your client now to handle 403 on any endpoint without breaking.

When the code changes (new enforced scopes, spawn-profile fields, memory-zone semantics, or any endpoint addition), this guide MUST be updated in lockstep and re-seeded into the kb_integrations knowledge page (add a new project_docs upsert migration — the original seed migration is immutable once applied).