shipyarddocs
shipyarddocs

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" } }
FieldMeaning
seqThe event's number in the box's journal, in the order things happened (boxes with the journal capability)
typeWhat happened, area.thing
timeWhen
boxThe box it happened on, or a laptop event's box (box.connected, forward.*)
originThe tool it came from: app, berth (the default), claude, detected, flow:<id>, guard, phone, a hook's tool…
errorFor failures
dataDepends 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

EventData
agent.readypath, 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.startedthe 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.waitingthe 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.finishedthe same: done with its turn; status: "error" when it ended on a failure
agent.exitedthe same: the agent itself quit
task.createdlocation, name, path, branch, session, agent, from_session
session.startedname, location, path, command
session.stoppedname
session.memoryname, location, memory, memory_high, near_limit, text: a session came near its memory limit (near_limit: true), or went well below it again
session.renamedname: its title changed (a rename, or its first prompt named it); never the title or the prompt
session.sentname, from, idem_key?, turn?: a prompt was typed in (never the prompt)
session.queuedname, turn: a prompt is held until the agent is idle (when: "idle")
session.openname, location, path, open, agent: asks the app to show a new session
exec.finishedlocation, path, command, exit_code
preview.openlocation, 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

EventData
location.addedlocation, path, url (when cloned)
location.removedlocation
worktree.createdlocation, 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.removedlocation, name, path
worktree.renamedlocation, name, path: its display name changed (set or cleared); never the name itself
worktree.setup.started, .finished, .failedlocation, name, path, script, log
worktree.archive.started, .finished, .failedthe same
worktree.syncedlocation, name, mode, ok, base, conflicts
worktree.paused, worktree.resumedlocation, name, path
service.startedlocation, name, path, service, port; session for a service in a terminal
service.stoppedlocation, 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.failedlocation, 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.

EventData
review.openedlocation, 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.updatedlocation, name, path, repo, pr, from, sha, author, association, reviewer: moved to a newer head the reviewer confirmed
review.waitinglocation, 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.removedlocation, name, path, repo, pr, reason: merged, closed, idle, or removed (by hand)
review.buttonrepo, 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

EventData
flow.startedflow, scope, run, path
flow.finishedflow, scope, run, status, path
flow.interruptedflow, scope, run, status: "interrupted", path: a run from before durable runs that was going when berthd stopped (imported once)
flow.skippedflow, 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.finishedrun, template, status, and flow, scope, path, title, group when set: a durable run
run.stepthe same, with step (its path), kind and step_status, as each step ends
run.gatethe same, with step, gate_title, pick: it waits for someone. A notify (kind: "run.gate") goes with it
run.gate_decidedthe same, with step, approve, by
browser.opened, browser.closedlocation, name, path; closed has reason (idle, closed, the guard, another worktree needing one, its worktree removed)
artifact.added, artifact.updated, artifact.removedid, 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.failedlocation, name, path, reason: sandbox (Chromium's sandbox can't start; see agent browser) or error
browser.navigatedlocation, name, path, tab, url: the agent browser loaded a page (tab is "" for the main tab)
browser.shotlocation, name, path, tab, file, url
browser.tab.opened, browser.tab.closedlocation, name, path, tab: an agent opened a tab of its own, or it closed; closed has reason (idle, closed, another tab needing room)
worktree.loginlocation, 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
notifytitle, body, flow, path, location: a flow's or the guard's notification
guard.actedaction, location, name, path, services, sessions, memory_percent, reason
process.stoppedid, text: a browser (or a session) was stopped from the box's browsers
config.changedwhat 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.installedlocation, 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.removedlocation, kit
team.startedteam, name, commit: a team setup started on the box
team.stepteam, step, state (running, waiting, done, skipped, failed), secs, code (GitHub's device code, while the box signs in)
team.projectteam, project, state (cloning, setting-up, ready, failed), location, error
team.doneteam, name
team.failedteam, step or project, error
team.retryteam, from
skills.installed, skills.removedskills, agents, target, location, paths
integrations.installedtool, 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.installedagents: agent CLIs were added to the box from the app (Add agents…) or POST /v1/agents/install
secret.failedlocation, name, path, variable, ref, reason: a secret reference could not be read, so the variable was left unset; never the value
secret.resolvedlocation, name, path, variable, ref: one that failed reads again
share.started, share.stoppedid, port, url
unit.started, unit.stopped, unit.restartedname
helper.installedplugin, name, version: a plugin's helper was installed on the box and turned on
helper.removedplugin, 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.changedenabled
phone.push.addedname, platform: a phone app asked to be notified (origin: "phone")
phone.push.removedname, 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.changedenabled, provider, url, model, key (a reference, or empty), key_pasted, key_removed; never a key's value
box.upgradedbuild
pairing.invitedfor, by, expires: a paired laptop (by, as laptop:<name>) asked for a pairing code for another computer (berth invite); never the code
client.pairedname, fingerprint: a laptop paired with the box
client.revokedname, 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

EventData
laptop.started
box.connected
box.disconnected, box.untrustednone; the envelope's error says why
box.routeroute (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.removedid, local, remote (and the envelope's error on a failure)
queue.changedqueued, failed
queue.deliveredid, box, session, attempts
queue.failedid, box, session, reason (never the prompt)
kit.addedkit, source; for a team setup's kit also team, and from and to when a newer commit of .berth changed it
team.acceptedorg, team, box, commit: a team setup was sent to a box
team.suggestionsorgs: the orgs of your projects that publish a team setup you haven't accepted changed (how Shipyard notices)
team.updateorg, name, from, to, changes, sudo: a newer commit of a team setup this laptop accepted, to review; once per commit
app.changedkey: 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.

GateData
before:location.addlocation, path, url
before:worktree.createlocation, name, branch, base; for a review also review: true, repo, pr, sha
before:worktree.removelocation, name, path
before:worktree.renamelocation, name, title ("" clears it)
before:worktree.synclocation, name, mode
before:worktree.pause, before:worktree.resumelocation, name
before:task.createlocation, name, branch, base, agent, command
before:session.startname, location, path, command
before:session.stopname
before:session.sendname; from the phone also from: "phone", and key for a key press
before:execlocation, path, command
before:run.starttemplate, path, steps, or flow, scope
before:run.approverun, step, approve: deciding a gate, from the app, CLI or phone
before:run.cancelrun
before:run.prrun, path, branch: a run about to push and open a pull request
before:artifact.addlocation, name, path, title, kind, id (when updating one)
before:artifact.removelocation, name, path, id
before:browser.openlocation, name, path, tab, url: an agent browser opening a page
before:browser.eval, before:browser.watchlocation, name, path, tab: running JavaScript in it, watching it live
before:browser.alloworigin: letting agents' browsers load a public origin
before:worktree.loginlocation, worktree, email: logging a worktree in as a dev user from the laptop (/__berth/login)
before:process.stopid: stopping a browser or session from the box's browsers list
before:kit.installlocation, kit, source
before:kit.removelocation
before:team.setupteam, org, commit: a team setup about to start on the box
before:team.retryteam, from
before:skills.install, before:skills.uninstallskills, agents, target, location
before:integrations.installtool
before:config.changelocation, flows, env or guard: what is about to change
before:phone.change
before:phone.pushid, name, platform, from: "phone": a phone app asking to be notified
before:turncheck.changethe same as turncheck.changed
before:location.removelocation
before:hooks.change
before:session.attachname
before:service.start, before:service.stop, before:service.restartlocation, worktree, service
before:unit.startname
before:unit.stop, before:unit.restartname
before:share.startport
before:share.stopid
before:flow.testflow, scope
before:box.upgradebuild
before:helper.installplugin, name, version: a paired laptop installing a plugin's helper, a program that will run on the box
before:helper.attachplugin, 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.invitefor, by: a paired laptop asking for a pairing code for another computer
before:client.revokename, fingerprint: removing a laptop from the box
before:event.emittype

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

VariableMeaning
BERTH_EVENTThe event's type
BERTH_EVENT_BOXIts box
BERTH_EVENT_ORIGINIts origin
BERTH_<FIELD>Each data field, upper-cased, with other characters as _: BERTH_PATH, BERTH_NAME, BERTH_LOCATION, BERTH_SESSION, BERTH_AGENT…
BERTH_ORIGINThe hook's tool, or hook: Shipyard commands the hook runs announce their events with it
BERTH_PLUGIN_DIRA 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.

On this page