Reference
Events and gates
Every event Shipyard announces, the gates that can refuse actions, and the variables hooks get.
The envelope
{ "type": "worktree.created", "time": "2026-10-03T09:12:44Z", "box": "devl", "origin": "app",
"data": { "location": "shop", "name": "checkout", "path": "/home/me/work/shop-checkout", "branch": "checkout" } }| Field | Meaning |
|---|---|
seq | The event's number in the box's journal, in the order things happened (boxes with the journal capability) |
type | What happened, area.thing |
time | When |
box | The box it happened on, or a laptop event's box (box.connected, forward.*) |
origin | The tool it came from: app, berth (the default), claude, detected, flow:<id>, guard, phone, a hook's tool… |
error | For failures |
data | Depends on the type; below |
Box events reach the laptop too: the laptop agent relays every online box's
events with box set. berth events and GET /v1/events stream them.
A box keeps its events in a journal (~/.berth/box/journal/, files of up to
16 MB, at most 256 MB and 14 days in all), so nothing that follows its
events loses one in a burst, and GET /v1/events?since=SEQ replays what
came after SEQ before streaming. The laptop agent uses it to catch up after
a reconnect or a sleep.
Anything can announce its own: berth emit TYPE key=value… on the laptop,
berthd emit TYPE key=value… --origin TOOL on a box. A type is two words
of lowercase letters, digits and dashes joined by a dot, each starting with
a letter and at most 32 characters; an origin is lowercase letters, digits
and dashes.
Box events
Agents and sessions
| Event | Data |
|---|---|
agent.ready | path, agent, session (when the hook knows it) and the tool's own id (below): a new agent at its prompt. After a finished turn turn check judged unfinished but not waiting on you, with source: "turncheck", choice and seq: the session stays finished, with unfinished: true for choice: "working" (something still runs) or parked: true for choice: "parked" (it waits on a reply or a later time); neither notifies |
agent.started | the same, with signal: prompt (working on a prompt) or tool (working again after an approval or an answer). For an agent that cannot say it started, Shipyard sends it at the send, with source: "send" and turn |
agent.waiting | the same, with reason (permission, question): needs you. Codex's async question box adds question_box: "async": its turn can end before the answer, and the session keeps waiting until you prompt again. At a startup question Shipyard sends it itself, with reason: "startup question"; after a finished turn turn check judged to need you, with reason: "turn check", source: "turncheck" and the model's choice (needs_input or blocked) |
agent.finished | the same: done with its turn; status: "error" when it ended on a failure |
agent.exited | the same: the agent itself quit |
task.created | location, name, path, branch, session, agent, from_session |
session.started | name, location, path, command |
session.stopped | name |
session.memory | name, location, memory, memory_high, near_limit, text: a session came near its memory limit (near_limit: true), or went well below it again |
session.renamed | name: its title changed (a rename, or its first prompt named it); never the title or the prompt |
session.sent | name, from, idem_key?, turn?: a prompt was typed in (never the prompt) |
session.queued | name, turn: a prompt is held until the agent is idle (when: "idle") |
session.open | name, location, path, open, agent: asks the app to show a new session |
exec.finished | location, path, command, exit_code |
preview.open | location, name, path, port, url_path: an agent asks the app to show a page (berthd preview) |
Agent events come from the agents' own hooks (berthd integrations install),
with the tool as their origin and the agent's own conversation id as
agent_session_id (Claude Code also sends session_id, Codex turn_id,
Cursor conversation_id and status). A hook names the Shipyard session it
runs in as session, from $BERTH_SESSION. Hooks spooled while berthd was
down carry spooled: true and the time they ran. Shipyard does not publish a
tool use (agent.started with signal: "tool") for an agent that is
already working: it would change nothing. Nor does it publish Codex's
notify (agent.finished with via: "notify") once the session's hooks
have said a prompt started: notify comes at the end of each of Codex's
messages, and its Stop hook ends the turn. When an agent's hooks cannot
tell, Shipyard reads the terminal and sends these itself with
origin: "screen" and source: "screen". See turns.
Locations and worktrees
| Event | Data |
|---|---|
location.added | location, path, url (when cloned) |
location.removed | location |
worktree.created | location, name, path, branch (origin detected when another tool made it); repo_config: untrusted or changed when the repository's config was not run because it is not trusted; main: { branch, status, behind?, error? } when a new branch from the default branch kept it current, status being current, updated, changes (its checkout had uncommitted changes), ahead (it has commits origin doesn't) or failed |
worktree.removed | location, name, path |
worktree.renamed | location, name, path: its display name changed (set or cleared); never the name itself |
worktree.setup.started, .finished, .failed | location, name, path, script, log |
worktree.archive.started, .finished, .failed | the same |
worktree.synced | location, name, mode, ok, base, conflicts |
worktree.paused, worktree.resumed | location, name, path |
service.started | location, name, path, service, port; session for a service in a terminal |
service.stopped | location, name, path, service; for a service in a terminal whose program ended by itself (Ctrl-C in its tab, a crash), session and exit_status |
service.failed | location, name, service, error |
Reviews
A pull request opened for review. Its worktree also
has the usual worktree.created (with review: true), setup and removal
events.
| Event | Data |
|---|---|
review.opened | location, name, path, repo, pr, sha (the commit checked out), author, association (GitHub's: MEMBER, OWNER, COLLABORATOR), box, reviewer (the reviewer's GitHub login), secrets: "shared", withheld (the names of the reviewer's own keys it does not get) |
review.updated | location, name, path, repo, pr, from, sha, author, association, reviewer: moved to a newer head the reviewer confirmed |
review.waiting | location, name, path, repo, pr, reason (merged, closed, idle): due for clean-up, but it has uncommitted changes or a session running, so it waits for the reviewer; once per reason |
review.removed | location, name, path, repo, pr, reason: merged, closed, idle, or removed (by hand) |
review.button | repo, pr, location, worktree, and as and path when set: berthd added the Review in Shipyard button to a PR's description, or put a new as or path in place |
Automation, config and the box
| Event | Data |
|---|---|
flow.started | flow, scope, run, path |
flow.finished | flow, scope, run, status, path |
flow.interrupted | flow, scope, run, status: "interrupted", path: a run from before durable runs that was going when berthd stopped (imported once) |
flow.skipped | flow, scope, error: a trigger that did not start a run (its hourly limit, or its queue is full) |
run.created, run.queued, run.started, run.resumed, run.finished | run, template, status, and flow, scope, path, title, group when set: a durable run |
run.step | the same, with step (its path), kind and step_status, as each step ends |
run.gate | the same, with step, gate_title, pick: it waits for someone. A notify (kind: "run.gate") goes with it |
run.gate_decided | the same, with step, approve, by |
browser.opened, browser.closed | location, name, path; closed has reason (idle, closed, the guard, another worktree needing one, its worktree removed) |
artifact.added, artifact.updated, artifact.removed | id, title, kind, location, name, path, version, and session when an agent made it; problem when a rewrite of its file wasn't taken. A rewrite the box noticed has origin watch; a visual diff from berthd shots compare has origin shots and its summary. See artifacts |
browser.failed | location, name, path, reason: sandbox (Chromium's sandbox can't start; see agent browser) or error |
browser.navigated | location, name, path, tab, url: the agent browser loaded a page (tab is "" for the main tab) |
browser.shot | location, name, path, tab, file, url |
browser.tab.opened, browser.tab.closed | location, name, path, tab: an agent opened a tab of its own, or it closed; closed has reason (idle, closed, another tab needing room) |
worktree.login | location, worktree, email, ok: a worktree was logged in as a dev user, from the laptop's /__berth/login, berthd browser open --as (origin is the caller's) or berthd shots compare --as (origin shots). email is empty when it wasn't a valid address. Never a cookie |
notify | title, body, flow, path, location: a flow's or the guard's notification |
guard.acted | action, location, name, path, services, sessions, memory_percent, reason |
process.stopped | id, text: a browser (or a session) was stopped from the box's browsers |
config.changed | what changed: location, flows, env or guard; with location, trust (trusted or untrusted) when the repository's config was trusted or no longer is |
hooks.changed | |
kit.installed | location, kit, version, source, warnings; for a team setup's kit taken on its own (just the kit) also org, commit, keys, init, first_open |
kit.removed | location, kit |
team.started | team, name, commit: a team setup started on the box |
team.step | team, step, state (running, waiting, done, skipped, failed), secs, code (GitHub's device code, while the box signs in) |
team.project | team, project, state (cloning, setting-up, ready, failed), location, error |
team.done | team, name |
team.failed | team, step or project, error |
team.retry | team, from |
skills.installed, skills.removed | skills, agents, target, location, paths |
integrations.installed | tool, account?: an agent CLI's hooks and skills were installed from the app or the API, or by berthd in an account folder a new session uses |
agents.installed | agents: agent CLIs were added to the box from the app (Add agents…) or POST /v1/agents/install |
secret.failed | location, name, path, variable, ref, reason: a secret reference could not be read, so the variable was left unset; never the value |
secret.resolved | location, name, path, variable, ref: one that failed reads again |
share.started, share.stopped | id, port, url |
unit.started, unit.stopped, unit.restarted | name |
helper.installed | plugin, name, version: a plugin's helper was installed on the box and turned on |
helper.removed | plugin, purged, attached: one was stopped and removed, with its data when purged; attached counts the running services that still point at it. Not announced when nothing of the helper was on the box |
phone.changed | enabled |
phone.push.added | name, platform: a phone app asked to be notified (origin: "phone") |
phone.push.removed | name, platform: a phone app is no longer notified: removed from the phone or a laptop, forgotten with a new code, or reason: "gone" when the push relay said it no longer takes notifications |
turncheck.changed | enabled, provider, url, model, key (a reference, or empty), key_pasted, key_removed; never a key's value |
box.upgraded | build |
pairing.invited | for, by, expires: a paired laptop (by, as laptop:<name>) asked for a pairing code for another computer (berth invite); never the code |
client.paired | name, fingerprint: a laptop paired with the box |
client.revoked | name, fingerprint: a laptop removed from the box from another one (Settings → Computers) |
Flows triggered by a schedule, GitHub or a webhook receive schedule.fired,
github.review_comment, github.pr_review, github.check_failed,
github.pr_merged, github.issue_labeled, github.issue_assigned or
webhook.received as their event; these start the flow directly and are not
announced to hooks.
A flow's scope is box or repo:<location>, whichever layer (committed,
kit or the box's own) the flow comes from; only the flow that wins its id
runs, so flow and scope name one flow.
Laptop events
| Event | Data |
|---|---|
laptop.started | |
box.connected | |
box.disconnected, box.untrusted | none; the envelope's error says why |
box.link | slow, reason when a box's link turns slow or steady again; none when Tailscale starts or stops relaying it. The box stays online either way |
box.route | route (the id of the route now in use), from, down (a route declared down, whose streams moved); none when a route was added or turned on or off |
forward.started, forward.failed, forward.removed | id, local, remote (and the envelope's error on a failure) |
queue.changed | queued, failed |
queue.delivered | id, box, session, attempts |
queue.failed | id, box, session, reason (never the prompt) |
kit.added | kit, source; for a team setup's kit also team, and from and to when a newer commit of .berth changed it |
team.accepted | org, team, box, commit: a team setup was sent to a box |
team.suggestions | orgs: the orgs of your projects that publish a team setup you haven't accepted changed (how Shipyard notices) |
team.update | org, name, from, to, changes, sudo: a newer commit of a team setup this laptop accepted, to review; once per commit |
app.changed | key: an app settings document changed |
hooks.changed |
Gates
Gates are before: hooks on a box. They run before the action, in order
(the box's hooks.json and plugins, then the repository's), and one that
exits non-zero refuses it with what it printed. Gates in a laptop's
hooks.json never run.
| Gate | Data |
|---|---|
before:location.add | location, path, url |
before:worktree.create | location, name, branch, base; for a review also review: true, repo, pr, sha |
before:worktree.remove | location, name, path |
before:worktree.rename | location, name, title ("" clears it) |
before:worktree.sync | location, name, mode |
before:worktree.pause, before:worktree.resume | location, name |
before:task.create | location, name, branch, base, agent, command |
before:session.start | name, location, path, command |
before:session.stop | name |
before:session.send | name; from the phone also from: "phone", and key for a key press |
before:exec | location, path, command |
before:run.start | template, path, steps, or flow, scope |
before:run.approve | run, step, approve: deciding a gate, from the app, CLI or phone |
before:run.cancel | run |
before:run.pr | run, path, branch: a run about to push and open a pull request |
before:artifact.add | location, name, path, title, kind, id (when updating one) |
before:artifact.remove | location, name, path, id |
before:browser.open | location, name, path, tab, url: an agent browser opening a page |
before:browser.eval, before:browser.watch | location, name, path, tab: running JavaScript in it, watching it live |
before:browser.allow | origin: letting agents' browsers load a public origin |
before:worktree.login | location, worktree, email: logging a worktree in as a dev user from the laptop (/__berth/login) |
before:process.stop | id: stopping a browser or session from the box's browsers list |
before:kit.install | location, kit, source |
before:kit.remove | location |
before:team.setup | team, org, commit: a team setup about to start on the box |
before:team.retry | team, from |
before:skills.install, before:skills.uninstall | skills, agents, target, location |
before:integrations.install | tool |
before:config.change | location, flows, env or guard: what is about to change |
before:phone.change | |
before:phone.push | id, name, platform, from: "phone": a phone app asking to be notified |
before:turncheck.change | the same as turncheck.changed |
before:location.remove | location |
before:hooks.change | |
before:session.attach | name |
before:service.start, before:service.stop, before:service.restart | location, worktree, service |
before:unit.start | name |
before:unit.stop, before:unit.restart | name |
before:share.start | port |
before:share.stop | id |
before:flow.test | flow, scope |
before:box.upgrade | build |
before:helper.install | plugin, name, version: a paired laptop installing a plugin's helper, a program that will run on the box |
before:helper.attach | plugin, location, worktree, path, from: a paired laptop asking the box to tell that plugin's helper of a worktree outside a service's start. from is .env when the box is to read the worktree's .env files for the variables the helper's manifest names, and .manual when a person gave them (a database's address, pasted in the Database tab); what was given is never in the event. A service's start is gated by before:service.start, not by this |
before:pairing.invite | for, by: a paired laptop asking for a pairing code for another computer |
before:client.revoke | name, fingerprint: removing a laptop from the box |
before:event.emit | type |
A gate's BERTH_EVENT_ORIGIN is what the box can vouch for: the tool named by
a caller on the box's own socket, or laptop:<name> for a paired laptop and
remote for the phone, whatever origin they claim. So a gate scoped to a
tool cannot be skipped from another machine by claiming to be that tool.
Gates stop mistakes and keep automations inside the lines you draw; they are
not a boundary against a paired laptop, which can already run commands on the
box.
A task runs before:task.create, then the worktree's and the session's own
gates.
What a hook gets
| Variable | Meaning |
|---|---|
BERTH_EVENT | The event's type |
BERTH_EVENT_BOX | Its box |
BERTH_EVENT_ORIGIN | Its origin |
BERTH_<FIELD> | Each data field, upper-cased, with other characters as _: BERTH_PATH, BERTH_NAME, BERTH_LOCATION, BERTH_SESSION, BERTH_AGENT… |
BERTH_ORIGIN | The hook's tool, or hook: Shipyard commands the hook runs announce their events with it |
BERTH_PLUGIN_DIR | A plugin's hooks: its folder |
The event is also on stdin as JSON. Hooks from a repository's config get the worktree's environment as well; see files and environment.