coss.comshipyard

The app's API

The loopback API the desktop app and plugins use, and the box API behind it.

The desktop app is only a view. It talks to the laptop agent (berth agent, which any berth command that needs it starts, and berth agent install keeps running as a service), which holds the connections to every box. When the agent isn't running, the app offers to start it (Start the Shipyard agent runs berth agent start; ticking Start at login runs berth agent install). Closing the app, or the app crashing, never stops an agent session or a forward.

Transport

The agent serves the app on http://127.0.0.1:1378.

  • Token. Every request carries Authorization: Bearer <token>. WebSocket upgrades, which cannot set headers from a browser, pass ?token=<token> instead; on any other request a query token is ignored, so it never lands in logs or history. The token is in <state>/client/ui-token (mode 0600); the Tauri shell reads it with the ui_endpoint command, which returns { "url": "http://127.0.0.1:1378", "token": "…" }. For browser-only UI work, berth ui-token prints the same JSON.
  • Host check. Requests whose Host is not 127.0.0.1:1378 or localhost:1378 are refused, so a web page cannot reach the agent through DNS rebinding.
  • CORS. Allowed origins are tauri://localhost, http://tauri.localhost, https://tauri.localhost, and http://localhost:1420 to :1439 (Vite in development). The token, not the origin, is what keeps other pages out.
  • Errors. A failed request answers { "error": "…", "code": "…" }. The message is for people and logs; branch on the code. The box's codes are not_found, session_exited (the session's program has ended, so it takes no input), session_exists, agent_waiting (sending now would answer its question), refused (a before: hook said no), unsupported, tmux_missing, git_failed, command_failed, too_many, bad_request and internal, and for plugins' helpers helper_off, helper_invalid, helper_mismatch, helper_missing and helper_unreachable. The agent adds box_unreachable (the request never reached the box, 503, or may have, 502), box_unknown (no paired box by that name) and box_outdated (the box's berthd doesn't have that route yet). A request for a box the agent knows is offline is answered at once with 503 box_unreachable and Retry-After (seconds to its next try), rather than after a dial timeout. The app gives each read (GET, but not a …/wait long poll) 30 seconds and then fails it as box_timeout (504).

Laptop

QueueItem is the offline prompt queue's entry (the offline queue):

{ id, box, session, text, enter, wait, state, error?, created, attempts?, last_attempt?, blocked?, seq }

state is queued (waiting for the box), waiting (the box is back; waiting for the agent's turn to end), sending, or failed with error. blocked marks one held behind an earlier failed prompt to the same session. wait (default true) holds a prompt while the agent is mid-turn; enter (default true) presses Enter after it.

The app also uses these, mostly as the CLI does:

POST /v1/stop is refused here: the app cannot stop the agent.

Boxes

ANY /v1/boxes/{box}/api/{path} is passed to the box as /v1/{path}, query string and body included, and the box's answer is streamed back. When the box cannot be reached the agent answers itself: 503 when the request never reached the box (safe to retry or queue), 502 when the connection failed after it went out (the box may have acted on it). The box API:

Session carries the agent's state when an agent tool reports it: agent (claude, codex, …) and agent_state (idle, running, waiting, finished), plus preset (the agent preset it was started with), turn (its current or last turn), state_seq and fidelity (hooks, partial or screen), queued (prompts held until it is idle) and, while it waits, ask (what its hooks said it asks for). exited is true once the program has ended. title names the work: the first line of the prompt it started with, or of the first prompt it was sent or typed, cut to about 48 characters; PATCH sessions/{name} with { title } renames it (an empty title clears it). Only the title is kept, never the prompt.

A Run is { id, template, title?, status, steps, gate?, candidates?, usage?, cursor?, params?, created, updated, finished?, error?, … }, with status one of queued, running, waiting_gate, paused, succeeded, failed, cancelled, interrupted; GET runs lists summaries (the same without steps). The info's capabilities lists runs and exec.detach on boxes that have them.

A Turn is { id, session, agent?, n, origin?, sent_seq?, end_seq?, state, queued?, started?, ended?, waits?, fidelity?, idem_key?, status? }, with state one of queued, pending, running, waiting, finished, exited, lost; see turns.

GET locations/{name}/config and GET env return secret references as written, never their values.

Terminals

GET /v1/boxes/{box}/sessions/{name}/attach?cols=C&rows=R&token=T upgrades to a WebSocket.

  • Box → app: binary messages, raw terminal output.
  • App → box: binary messages are keystrokes; text messages are JSON {"type":"resize","cols":C,"rows":R}.

Closing the socket detaches; the session keeps running on the box. Attaching again redraws the screen, so the app reconnects after sleep or a network change by opening a new socket. When the route the terminal rides goes down, the agent attaches again over another inside the same socket: the screen is redrawn, and keys that may not have reached the box are sent again first.

Events

{ "type": "agent.waiting", "time": "…", "box": "devl", "origin": "claude",
  "data": { "path": "/home/me/work/shop-checkout", "agent": "claude", "session_id": "…" } }

The app reacts to most box and laptop events: connections (box.*), locations and worktrees (location.*, worktree.*, service.*), sessions and agents (session.*, agent.*, task.created, preview.open), automation (flow.*, guard.acted, config.changed, hooks.changed), kits, team setups (team.*), shares, forwards, units, the queue (queue.*, never the prompt) and secrets (secret.*, never a value). Events and gates lists every type and its data.

Last updated