Configure
Permissions and sandbox
Ocean Code decides what a tool may do in three layers, from softest to hardest:
- Permission rules and modes — an ask/allow/deny policy over each tool call.
- The shell and filesystem guards — a classifier that reasons about what a
bashcommand or a file edit actually does, on top of the rules. - The kernel sandbox — OS-level isolation the process cannot talk its way out of, off by default.
An empty config is not an asking one: the base rule is * * allow, so a tool call
is allowed unless something fences it — the shell's dangerous floor, an
external_directory ask, a denied .env read, a land ask (the Ocean Git
workspace commit, pattern = the branch, so "land": {"andreas/*": "allow"} lands
your own branches without asking; 21).
Secret-named environment variables
are stripped from child processes and .env files are never read into the model.
Add bash * ask under permission to make every shell command off the read-only
safe list ask; that is also the posture the Jev permission advisor works on. This
page is how to loosen or tighten each layer.
Permission modes
A mode is a coarse posture layered over your permission rules. Set the boot
default with permission_mode in the config (see
02 · Configuration), or switch it live over the HTTP API
(see Switching the mode live below).
| Mode | What it does |
|---|---|
(empty) / default | Evaluate the rules as written; with the base * * allow rule a call no rule fences is allowed. |
acceptEdits | Auto-allow edit; everything else is unchanged. |
dontAsk | Never block on an interactive ask (a residual ask resolves to deny in a headless posture). |
bypassPermissions | Auto-allow everything — except the dangerous floor below, which no mode can reopen. |
Ocean TUI's auto (the Shift+Tab Auto stop, /auto) is acceptEdits and its
always-approve (ctrl+o, /always-approve) is bypassPermissions; the TUI sends every
change to the engine (see 19 · Ocean TUI).
A permission ask nobody answers is rejected after 30 minutes, and the reject is announced, so the TUI's card and the Slack message close instead of waiting forever (0.8.8.68).
A mode is expressed as ordinary last-match-wins rules, so it can never silently
override the safety floor: bypassPermissions appends an allow-all rule, but the
dangerous-floor deny is evaluated first and wins regardless.
Jev advisor. With the opt-in Jev decision layer on (see
13 · Jev decisions), a residual ask on a bash command — one
that no allow, deny or specific-pattern ask rule settled — is first put to Jev as
four bounded questions (in act the prompt waits at most jev.deadline_ms, 1.5 s by
default). With the empty config's * * allow base there is no such ask, so the
advisor sees nothing until a rule such as bash * ask makes the shell guard ask.
In shadow, the default once the layer is enabled, the call runs in the background, its
answer is only recorded and you are asked as before, without waiting. With jev.permissions = "act" a command inside a bounded
safe class — not destructive, no network egress, easily undone, a single-file or
project blast radius — runs without the prompt. The dangerous floor and deny rules
run before the advisor and never reach it, dontAsk gets no advice, a command that
names a path outside the project (or runs in a workdir outside it) gets none
either — the shell guard checks that in code — and a fixed hold list (package
installs and publishes, git push, recursive rm, ssh, an uploading curl, an
interpreter run on a file, …) always asks. Under headless --auto, an act advice
that the command is destructive, sends data out, reaches the system or a third
party, or tripped the injection guard rejects the call instead of approving it, and
the rejection carries the reason and the Jev scores back to the model as feedback
(see 13). Your answer to an advised prompt is
recorded as that decision's label.
Rule syntax — Tool(pattern)
Individual permission entries and the shell.allow / shell.deny lists take a
Tool(pattern) form, e.g. Bash(git push:*), Edit(src/**), Read(*.md). The
tool name is matched case-insensitively; an empty pattern means *.
A tool whose last rule for its key is a * deny — bash * deny, or a read-only
agent's blanket deny — is not offered to the model at all: its schema is left out of
the request (write, apply_patch and hashline count as edit). A narrower last
rule keeps the tool, so the plan agent still sees edit for its plan file. Sub-agent
children are sent the built-in tools only, never MCP or skill tools, and their system prompt
carries no skills list (they could not load one).
MCP calls — the mcp key
Every MCP tool call passes the rules under the key mcp with the pattern
<server>/<tool>, e.g. "mcp": {"github/*": "allow", "github/delete_repo": "deny"}.
When no mcp rule decides, the server's origin does: a server declared in config
(the project's .oceancode/oceancode.json or your global oceancode.json, a user-tier
~/.claude.json, the project-local tier) or passed by the client (the servers Xcode
passes) runs without asking; a server from the project's .mcp.json, a plugin or a
runtime add (POST /mcp, the TUI's /mcp add) asks, and "always" approves the whole
server. Config servers are not trust-gated, including those in a .oceancode/oceancode.json
committed to a checkout: read that file before you open a repository you don't trust. The server's own readOnlyHint is never
used: the server supplies it. A headless oceancode run without --auto cannot ask,
so it refuses the call and tells the model the rule that approves the server. Trust
is the separate gate that decides whether such a server runs at all
(11 · MCP servers).
Switching the mode live
The permission mode is switched at runtime over the HTTP API —
GET/POST /api/session/{id}/permission/mode (see
07 · Headless and server). A managed
(enterprise) requirements file can lock out bypassPermissions: once locked,
selecting it downgrades to default.
The shell guard
Before any bash command runs, a classifier splits it into segments, peels
wrappers (sudo, env, nice, timeout, xargs, bash -c "…", VAR=val …),
and decides allow / ask / deny per segment. The whole command runs only if
every segment is allowed (a chaining guard — git status && rm x still asks).
- Read-only safe list. Commands that only read (
git status,git log,ls,rg,grep,find, …) auto-approve with no rule. The list looks at flags:findwith-delete,-exec,-execdir,-ok,-okdir,-fprint,-fprint0,-fprintfor-fls;git branchthat deletes, renames, copies, forces or re-points (-d,-D,-m,-M,-c,-C,-f,-u,--delete,--set-upstream-to,--unset-upstream);git remotewithadd,remove,rm,rename,set-url,set-head,set-branches,pruneorupdate; andgit tagthat creates, signs, forces or deletes (a name aftertagcreates a tag unless-l/--listmakes it a pattern) are off the list and ask. Adding output redirection (> file) drops a command off the safe list. - Dangerous floor. A fixed set of destructive shapes is refused outright and
no permission mode can reopen it:
rm -rf /(and obfuscated variants),git push --force,dd of=/dev/*,chmod -R 777 /,mkfs*, the fork bomb, andcurl … | sh. The floor peels wrappers and unwrapsbash -c/command substitutions, so hiding the command behindsudo,/bin/rm, or$(…)does not evade it. shelloverrides.safe_list_extraadds read-only commands;allow/denylayerTool(pattern)rules onto the classifier. Neither can remove the dangerous floor.
Child-process environment
Every bash and PTY child gets a composed environment rather than a raw copy of
the parent's. By default, variables whose name contains KEY, SECRET, or
TOKEN (case-insensitive) are stripped, so a secret in your shell never
leaks into a spawned tool.
Tune it with child_env:
| Field | Meaning |
|---|---|
inherit | all (default), core (only PATH/HOME/USER/SHELL/LANG/TERM/TMPDIR), or none. |
include_only | When non-empty, keep only these variable names. |
set | Extra name→value entries overlaid last. |
strip_secrets | Drop secret-named variables (default true). |
The sandbox
The sandbox confines a spawned child at the OS level — sandbox-exec (Seatbelt)
on macOS, bubblewrap (with Landlock where the kernel supports it) on Linux ≥
5.13. It is off by default; turn it on with the sandbox config.
| Profile | Reads | Writes | Network |
|---|---|---|---|
off | unrestricted | unrestricted | unrestricted |
workspace | workspace + writable roots | workspace + writable roots | per network |
readonly | workspace + writable roots | denied | per network |
strict | workspace only | workspace only | per network |
denylists roots refused even inside the workspace (e.g..git, a secrets dir).networkisoff(no egress) orallowlist. The allow-list is not enforced yet: on macOS and Linux anallowlistpolicy leaves egress open, because no child's traffic is routed through the TLS-SNI relay. Useoffto block egress.
On a Linux kernel older than 5.13, Landlock is unavailable and bubblewrap alone provides the confinement (a warning is logged, never a silent disable).
Reference aliases
refs maps a short @name to a directory. A path of the form @name/rest in any
file tool (read / edit / write) expands to <refs[name]>/rest, and that
reference root is auto-allowed through the external-directory prompt — so a shared
docs or vendor tree can be reached without a prompt for every file. An unknown
@name is left literal and still prompts, and an alias that walks out of its root
(@name/../escape) is caught by the external-directory boundary just like any
other outside path.
Filesystem guards
The file tools carry their own safety, independent of the rules:
.envis never read.readrefuses.envand*.env/*.env.*files (secrets);.env.examplestill reads.- Read-before-write.
writerefuses to overwrite an existing file you have not read this session ("file exists but has not been read this session"); a brand-new file writes freely. One exception (2026-09-28): a file under 64 KiB that this session itself created — its birth time is at or after the session's first tool call in this process, e.g. a file abashcommand generated — can be overwritten without a read. A file that existed before the session is refused even when it was edited since, and on a filesystem that reports no birth time the exception never applies. - Stale detection.
editandwriterefuse a target that changed on disk since it was last read — detected by content hash, so a same-size, same-mtime change is still caught. Read it again first. Other files changing — a build, a file abashcommand wrote, the session's own database — never cost you a read: a read stays valid until the file itself changes (2026-09-28). When another Ocean Code session wrote the file since your read, the refusal names it:… read it again before overwriting (changed by session "wake-visible" (2 min)).
Session peers
Every Ocean Code engine on the machine (a TUI window, oceancode acp, oceancode serve,
the short commands peers, status and resume, the Ocean app) joins one switchboard,
the session line (2026-11-18; from 2026-10-28 it was one shared SQLite file every engine
read on a timer), so sessions running side by side in one checkout do not overwrite
each other. Nothing about another session enters a prompt on its own: the model
hears about one when it is about to touch that session's file, when it looks (the
sessions tool below, or recall across sessions,
06 · Recall across sessions),
or when you accept a request.
- On the line. The first engine started hosts the line on a loopback port
(
127.0.0.1; the port and a token are in<data dir>/line/addr, readable only by you); the others connect to it. When the host closes, the next engine takes over, and the others join it again and claim again what they held; a call that was under way is sent once more. Only the host writes the record,<data dir>/line/messaging.db: a row per root session (title, directory, state, what it is doing), the claims, the requests and the log. An engine whose connection closes is gone at once: its sessions are cleared with everything they held (expiredin the log) and their cards readcrashed, so a crash blocks no one. After the host changes, an engine that has not come back within 3 s is cleared the same way. The host tells every engine of each change as it happens; no engine reads the file on a timer. - Automatic claims.
write,edit,apply_patchandhashlineclaim the file they change until your turn ends; a sub-agent writes under its root session's claims, and while a background sub-agent still works they last until it finishes. No model action is needed. A turn that runs on lets a file go earlier: once nobody in the session has written it for 10 minutes the claim ends (releasedin the log,not written for 10 min), and every write starts the 10 minutes over, so a long run holds the files it is working on, not every file it touched once. After the Mac sleeps the 10 minutes count from the wake. A session that comes back to a file another one changed meanwhile is refused (file changed on disk since it was last read … (changed by session "…")) and reads it again; a file let go no longer routes a request (below) to the session that wrote it. - Check before writing. A file another live session is writing is refused
before anything is written, naming it:
runner.rs is being written by session "wake-visible" (4 min, "turns fix"); work on something else or try again later(blockedin the log; the session's row readsblockeduntil its next write succeeds). The time is how long ago that session last wrote the file (or, for aclaim, took it).apply_patchchecks every file of the patch first, so a refusal leaves the tree as it was. A file the turn claimed stays claimed, as above, even when you reject the write at the permission card. - The
claimtool.claimholds a file, or work that is not one file (name:consulting-regress), for up to 60 minutes, past the end of the turn and whether or not the file is written;releaselets it go. It covers what a script writes insidebash, which the file tools never see. - Your override.
/peers take <path | name:label>in the TUI gives the claim to your session (overrodein the log). It becomes a claim of your session's turn, whatever time a takenclaimhad left: held until your next turn ends, or let go 10 minutes after the take or your session's last write. - Slots. A build or a deploy that two sessions must not run at once is a
slot, named in the project's map
.oceancode/areas.json(2026-11-14). Before abashcommand runs, the engine claims every slot the map names for it, asname:<slot>; while another live session holds one, the command is refused with that session's name (deploy:oceanbase is needed by this command and is held by session "…" (<1 min, "running: …"); work on something else or try again later). While that session stays open, it keeps the slot for three quiet minutes after its command ends, so a second run of the same build waits; a background job holds it until the job ends (renewed every 30 minutes; if another session took it meanwhile, the log saysslot_lost). A session that closes or dies frees its slots with its claims (On the line, above). A claim you took by hand on the same name keeps its time. Without a map nothing is claimed; a map that cannot be read turns slots off and says so once, in the firstbashresult. A slot's time counts while the Mac is awake: after a sleep, every timed claim of this Mac ends that much later. A claim held for a session on another machine keeps that machine's time (0.8.8.112; before, it moved too). - Deploy slots and the live check. A deploy slot (its name starts with
deploy:) is refused before it runs while its generated file is older than its sources (fresh:wrangler.jsonc is older than wrangler-templates/…; run \npm run update-config` first), or while another session writes a file under the slot's folder (deploy_refusedin the log). After a deploy that exited 0, its result names the files other sessions wrote under that folder since the last deploy, and the slot'slivecommand runs, up to three tries 10 s apart. Passed, the slot is free (live_ok); failed, it stays this session's for up to 60 minutes (waiting for live check: …,live_failed`) until the live command passes in that session, run by hand or with the next deploy. - The hold (0.8.8.107). A service whose live check failed is on hold: every
other session's deploy of it is refused with the reason (
deploy:demo is needed by this command and is held by session "…" (<1 min, "waiting for live check: …")). The failed check also leaves aholdrow in the log, and its result lists the lands under the slot's folder since the check last passed, newest first (at most ten), so the fix starts from the changes that can have caused it:Lands under svc since the check last passed, newest first: 1111aaaa2222 on main by "#ab12" (2 files, 12 min ago); …. A passing check frees the service at once. - Lands in the log (0.8.8.107). A
landfrom an Ocean Git workspace logs onelandedrow per file (1111aaaa2222 on main, withrebasedwhen Ocean Git applied it on top of a branch that had moved). A land that was refused logsland_refusedfor each file it ran into:conflict on main at <head>,rejected <status>: …, orguard: …(below).oceancode peers cardcounts them (21). - Shared documents. A file the map gives the kind
shared(log notes, changelogs, user-guide pages) is held only while it is written, not until the turn ends. Two sessions write it in turn. As with any file, a session reads it before its first write, and the one that fell behind is told the file changed on disk and reads it again. - After a command. When a
bashcommand changed a file another session is writing, its result says so (This command changed x.rs, which session "…" is writing. Tell that session, or put the file back.,overwrotein the log), unless the change may be that session's own: it wrote the file meanwhile (with a write tool, or with a command of its own, logged aswroteby a commandwhen that command ends), or it is still running a command, unless this command writes the file itself: a redirection (echo x >> notes.md),tee,sed -i,perl -i, the target ofcp,mv,rm(0.8.8.111; 0.8.8.110 named nobody then). A command that only reads it (cat,rg) is never named. A third session that changed the file meanwhile is not told apart from this command. A failed check (cargo test,check.sh, …) is logged with the folder it ran in (check_failed). - Overlap at approval. When a plan is approved, the files and folders its
to-dos name (paths with a
/; a bare file name or a glob is not placed) are reserved for that session. If another session's approved plan, or a file another session is writing now, meets them (the same path, or a folder holding the other), the build agent's first message lists each one:src/a.rs is in the approved plan of session "…" (…). Nothing is refused, and each overlap is loggedoverlap. Every path a to-do names is reserved, also one it only reads. While a plan is a draft, writing the session's own plan file (with any write tool) shows the same lines and reserves nothing; once it is approved, writing it adds nothing. A new approval replaces the session's set. A plan set todoneorabandoned(in the file, or by abandoning it at review), and a session that closed, whose engine left the line or that left its window, give their reservations back. - Generated files. A file the map gives the kind
generated:<command>(for this repositorywrangler.jsoncandworker-configuration.d.ts, made bynpm run update-config) is refused bywrite,edit,apply_patchandhashline, with or without the peers store; the refusal names the command, for example: wrangler.jsonc is generated by npm run update-config; change its sources and run that instead. - Changed on disk.
apply_patchandhashlinerefuse a file that changed since the session read it, with the wordsedituses, naming the session that changed it when there is one. - Who reads and writes where. Every write logs
wrotewith the lines it changed (lines 12-14,new file,deleted;oceancode peers logshows them). A read is never refused; when another session holds the file, the result ends with one line:Note: session "…" (2 min) is writing this file now (lines 120-134; plan row "3 Fix the parser").With no holder, nothing is added. The board shows each session's last file and lines on anat:row. - A file you read changed. When another session writes a file this session read, the next step carries one notice naming the file, the lines and that session, once per change. The session's own writes say nothing.
- Plan steps keep what they wrote. In a session with an approved plan, the
files the session has written while a to-do is in progress stay held after its
turn ends, with the reason
plan step <id>: <text>, until 30 minutes after its last write; another session's write to one is refused naming the step. A path the step only names, and a file it has not written, are never held. A completed to-do gives its files back (released … step done), and a session that stops writing (waiting on a question, say) lets go 30 minutes after its last write. - Unprotected writes. A write that went ahead because the store failed is
logged
unprotectedonce the store answers again, and the board shows that session asunprotectedfor ten minutes.
The map's slot lines, for one area and one slot at the top:
{
"slots": {
"deploy:*": { "run": ["wrangler deploy --env *"],
"fresh": { "file": "wrangler.jsonc", "newer_than": "wrangler-templates/*.jsonc" } }
},
"areas": {
"ocean-code/base": { "slots": {
"deploy:oceanbase": { "run": ["wrangler deploy --env oceanbase"],
"live": "curl -fsS https://base.plungeai.com/health" },
"build:oceanbase": { "run": ["ocean-code/base/build.sh"] } } }
},
"files": { "log/*.md": ["shared"], "**/CHANGELOG.md": ["shared"] }
}A command form's first word is a command name, or a script path from the project
root; its other words must follow in that order, and * matches one word and
fills the * of the slot's name (wrangler deploy --env staging takes
deploy:staging). An exact form wins over one with *. A form and a command are read the same way:
a leading npx, bash, node (and the like), VAR=value or timeout is
dropped, so bash build.sh and build.sh are one form; in the command,
cd <dir> && moves the folder the rest runs in.
live_retry_s changes the pause between live tries.
- Requests to another session. When the agent finds work that is not its
own — a bug in a file another session is writing — it can send a short request
with the
ask_sessiontool (the lead agent only; never a sub-agent). You can send one yourself to a session you pick, from Messages or with/message #abcd <text>(19 · Messages). For an agent's request, Ocean Code picks who gets it, in this order: the session on this Mac holding a claim on the paths named (a folder inpathsmatches a file claimed under it; a session on another machine never gets one, 0.8.8.112); else an empty Ocean Code window in the same project — the same folder, or one inside the other — opened, never prompted, the one opened first; else nobody yet: it waits and goes to the next empty window you open there. Only Ocean TUI windows from 0.8.8.53 on receive requests; an editor session (oceancode acp) or an older TUI is passed over. A session that has done its work never takes another session's new work: only the owner of the files, or a fresh window. An empty window that takes other work, or moves on, gives the request back, and it waits for the next empty window. You decide in the receiving window's Messages › Inbox: accepting runs it as that session's next prompt (after the running turn, if one runs), declining ends it. The asking agent is told where it went and carries on; it is never sent an answer. Its window showsr12 delivered to #f2k1once the receiving window has the request (2026-11-18; right after a/messageit readsSent r12 to #f2k1 · delivered), thenr12 accepted in #f2k1, thendonewhen the turn that ran the request's prompt finishes, orstoppedwhen that turn was cancelled, failed or stopped by a bound (a turn of an earlier queued prompt does not count; a turn that left background work running waits until that work's turn ends). Deleting the request's queued prompt before it runs, or a hook blocking it, withdraws it: it readsdeclined. Thesessionstool lists requests without their text: another agent's text reaches a model only as the prompt a user accepted. - Request guards. 1 to 2000 characters, cleaned of control characters when
stored; at most three open requests per session; one open request between the
same two sessions (and one waiting for an empty window per session, which also
keeps that session from asking an empty window directly while it waits); an open
request expires after an hour, and an open or accepted one when its receiver
closes. Rows leave the file a week after their last change.
oceancode statuslists the last day's requests.
Claims protect one session from another. Two TUI windows open on the same session
share its claims, so they do not keep each other off a file. They do keep apart
on a sub-agent: each engine marks the sub-agents it is running, so a message to
a sub-agent another Ocean Code process is running is refused, naming that process
(sub-agent "ses_…" is running in another OceanCode process (pid 45683, session "…", 14 min); message it from that window, or wait until it finishes), rather
than starting a second copy of it beside the first.
Engines from 0.8.8.40 until the session line shared the old file <data dir>/peers.db, whatever their number. An
engine with the line never writes that file: it reads it once, read-only, to carry over the cards, the log, the
Slack message rows and the machine id. Older engines keep using the old file among themselves and do not see the
new ones, so restart the open windows after the update. A session's row appears when its first turn starts. The
record's layout marker (PRAGMA user_version) only ever goes up, so a host of an older build that opens a newer
build's record leaves its rows and claims alone.
The TUI lists every session with what it does on the row under the Ocean bar (idle, thinking, reading, writing, running, needs you, blocked, empty), and in a short window as the chip ⇄N OC idle
(19 · Ocean TUI); oceancode peers lists them and
oceancode peers log prints the history (21).
An engine that cannot join the line checks nothing and says so once in its log. Engines that start in the same
millisecond end with exactly one host: each tries to join or to host for about 5 s. A stale addr (the host gone,
its port reused by another program) fails the handshake, and the engines elect a new host.
Switching it off
Three switches decide how much your windows take part. Each is on until you turn it off in F2 › Messaging, which
writes your user oceancode.json; Messages shows their states and s there opens that section:
{ "peers": { "awareness": true, "requests": true, "machines": true } }peers.awareness(F2 › Messaging "See other sessions").- The TUI stops listing other sessions on the row under the Ocean bar, and shows no
⇄Nchip. - The agent no longer gets notes about other sessions: a read of a file another session writes, the session's name on a "changed on disk" refusal, "Another session changed files you read", "This command changed …", and the overlap paragraph when a plan is approved.
- Writes stay checked. A file another session is writing is still refused, naming that session, because the check protects that session's work as much as yours.
- Messages › Sessions (
/peers, or/messagesand Tab) still lists them when you open it.
- The TUI stops listing other sessions on the row under the Ocean bar, and shows no
peers.requests(F2 › Messaging "Messages between sessions").- This window takes no messages. A new one goes to another window or waits, and one already waiting here goes back to waiting for another window. A message a user sent to this window keeps waiting for it.
- The agent's
ask_sessionanswersRequests between sessions are turned off here. Carry on with your own work. - The tool stays in the agent's list, so the switch changes no prompt byte.
peers.machines(F2 › Messaging "Share with other machines"). This only matters with a hub marker (Across machines).- This engine shares nothing with other machines: its writes are no longer claimed in the hub database, its sessions leave the database, and the other machines' claims are no longer mirrored here.
- Turned on again, it joins at once. Without a marker the switch changes nothing.
A change applies at once in the window that made it, and within about a second in every other open window, which
watch the config file. Your user file outranks a project's oceancode.json; only a managed config overrides it
(Config file locations).
Who accepts a message
A message between sessions runs only after it is accepted. By default a person accepts: in a terminal window
in Messages › Inbox, and for a session with no terminal window (oceancode serve, oceancode acp, a Factory desk)
in whatever shows its inbox over HTTP, such as
Ocean Terminal's Bridge. A session with no window and no such client takes no messages; the sender reads
takes no requests.
An engine can instead accept by itself, but only from the senders you name:
{ "peers": { "accept_from": ["#2oca", "ses_01JDX0000000000000000abcd"] } }- Each entry is a session's code (
#2oca, as Messages › Sessions shows it) or its full id. - A message from a named sender to one of this engine's sessions is accepted and runs as that session's next prompt, as soon as the session line reports it. A message from anyone else waits for a person, as before.
- The list is empty by default, and nothing accepts everyone. A code names a running session, so a list is for an engine you start for a task, not a standing permission.
OC_PEERS_ACCEPT_FROM(the same entries, separated by commas) sets the list for one engine at start and replaces the config's list; set and empty, a person accepts.- A change to
peers.accept_fromapplies at the next change on the session line, without a restart.
Across machines
The session line covers one machine. When a repository is worked on from several machines, each in its own checkout, a
file .oceancode/ocean-hub.json in the repository ({"database": "<id>"}, committed with it) puts every
write's claim into one Ocean Base (opens in a new tab) database as well, by its path from the folder that
holds .oceancode/:
- A write that the line lets through claims its file there too, once per file while held. When a session on
another machine holds it, the write is refused with a local refusal's words:
src/a.rs is being written by session "#ab12 on mac-2" (3 min); work on something else or try again later. When the database does not answer, the write goes ahead, its result says once per session that it is not protected against other machines, and the peers log gets anunprotectedrow. - Hearing the others. Every claim updates the database's one-row collection
bells, whose broadcast rule rings the public topicbellon Ocean Realtime. Each engine keeps one socket on it; each bell, every 30 s, and every reconnect read the other machines' live claims, which the line's record then holds as claims of sessions named#ab12 on mac-2. The board lists them and the write gate refuses their files with no network call. A mirrored claim ends at its own time, so a lost line stops refusing within minutes. - Letting go. Every 40 s an engine renews its sessions and their claims, with the file and lines each works on, and releases what the line no longer holds: a turn's files when it ends, a plan step's files 30 minutes after its last write. A claim not renewed lives 10 minutes; a session not renewed for 3 minutes counts as gone. A closing engine removes its sessions at once. An engine that slept or was offline longer than that may have lost files to another machine: after each renewal it reads which claims it still has, and claims the others again at their next write (0.8.8.105; in 0.8.8.104 it went on trusting them).
- Slots and named claims (0.8.8.106). A slot a
bashcommand takes and aclaimofname:<label>are claimed in the database under the same name, so a build or a deploy runs on one machine at a time:demo is needed by this command and is held by session "#ab12 on mac-2" (3 min); work on something else or try again later. A file claimed with theclaimtool is claimed across machines as a written one is, and a release with the tool leaves the database at once. When the database does not answer, the command runs and its result says so once per session. - Approved plans (0.8.8.106). The files an approved plan names go to the collection
planswith the next renewal, and each engine holds the other machines' plans in the line's record. An approval that meets one names it as it names a plan on this machine:crates/x (meets crates/x/src/a.rs) is in the approved plan of session "#ab12 on mac-2". It is shown, never refused. A plan reaches the other machines within about 40 s of its approval and leaves them when it is done or abandoned, or when its engine closes. A database withoutplans(made from the YAML of 0.8.8.104 or 0.8.8.105) keeps every claim working and keeps plans on their machine: apply the YAML below again, which adds the collection and changes no row, and start the engines again. - The board.
oceancode peerslists a session on another machine as#ab12 on mac-2with the files it holds and, as of its last renewal, the file and lines it works on (doing: src/a.rs lines 12-14) (0.8.8.106). - The log. A refusal that comes from another machine is a
blockedrow againsthub:<session>with the noteremote, and the refused session readsblockedon the board, as after a refusal on this machine (0.8.8.106). - Lands (0.8.8.107). After a
land, its files, the lines the session changed in each, the commit and the branch go to the collectionlands(at most 200 files a land, kept seven days). Every other machine reads the rows it has not heard, once: a session there that read one of the files is told at its next step (src/a.rs lines 12-14 (landed 1111aaaa2222, not here yet), by session "#ab12 on mac-2"), and the land is in that machine's log too, where a hold finds it. - A service on hold (0.8.8.107). A hold (above) goes to the collection
holdswith its reason. A deploy of that service on another machine is refused with the same words as on the holder's machine, the reason included. A passing check removes the row. A database withoutholdsstill refuses the deploy, through the slot's claim, without the reason. - Left on a machine:
"keep": true(0.8.8.107, off unless the marker sets it). A claim stops two writers but moves no content: a file changed on one machine and not landed is old on every other machine. With"keep": truein.oceancode/ocean-hub.json, the collectionkeptnames for each file the machine that changed it last and the content it left (git's blob id, sent with each renewal and when the engine closes). A write on another machine goes through only when its checkout holds that content; else it is refused:src/a.rs was last changed on "mac-2" (12 min ago) and this checkout does not have that change; get it here first (a land there and a sync or pull here), or work on something else. The row moves to the machine that writes the file next and goes seven days after its last change. Nothing takes a file over from a machine that never comes back before those seven days: leave the switch off until your team can live with that, or add the next switch. - A draft on the server:
"draft": true(off unless the marker sets it, and only with"keep": true). With it, the content of a held file that is not landed also goes to Ocean Git: at each renewal (every 40 s, and when the engine closes) the engine sends every held file whose content changed to this machine's own branch<handle>/draft-<machine>, as one commit, and the collectiondraftsnames that commit. A write on another machine of a file left there is then no longer stuck: when that checkout still has the content the other machine started from, the engine writes the other machine's content into it and answers oncesrc/a.rs was last changed on "mac-2" and was not landed; that content was just written into this checkout from its draft on Ocean Git. Read the file again, then make your change. The next write goes through, and the file is this machine's. In every other case the refusal ofkeepstays: this checkout changed the file itself, the draft is not the content the other machine left (its engine died within 40 s of a change), or Ocean Git does not answer. Read this before you switch it on:- Who can read a draft. Every holder of a token to the repository on Ocean Git. A draft is sent without a
question, where
landasks you. A file git ignores is never sent, nor is a symlink, a file over 1 MB, or any file in a folder that is no git repository. - It stays. The store has no garbage collection: about 8 KB a commit is kept for good, also after the branch is deleted. The branch is a bag of files and never lands; delete it when you like.
- What a machine needs. Its Ocean Git handle in
OC_OCEAN_GIT_HANDLEand that handle's token (the keychain itemocean-git/<handle>, elseOC_OCEAN_GIT_TOKEN). Without them the machine sends and takes no draft and behaves as withkeepalone.
- Who can read a draft. Every holder of a token to the repository on Ocean Git. A draft is sent without a
question, where
- Messages across machines:
"messages": true(0.8.8.128, off unless the marker sets it). With it, a session can write to a session on another machine as it writes to one on this Mac: the other machine's sessions that take messages can be picked in Messages › Sessions (taggedother machine),/message #f2k1 <text>andPOST /messaging/sendreach them, and the answer comes back (delivered,accepted,done). What it sends to the database, and to every machine that shares it: for each session that takes messages (a window, or a server whose client reads its inbox) its session id and this machine's host name, and each message's text until seven days after its last change. No session title and no folder is sent: another machine reads#f2k1 on mac-2. What to know before you set it:- The database needs the collections
inboxesandmessages(in the YAML below; add them to a database you already have withPUT /v1/databases/<id>/schema). Without them the switch does nothing and the rest works. - A person accepts a message from another machine, as from this one. An engine accepts one by itself only when
peers.accept_fromnames the sender by its full id,hub:ses_…: a code is not unique across machines. - Only a person's message crosses machines. An agent's
ask_sessionstays on this Mac. - There is no waiting line: when the database does not answer, the message is refused at once (
Not sent: …) and nothing is kept. A message still open after an hour readsexpiredon both machines. peers.machinesoff stops it with the rest: this machine's sessions leave the list, and the open messages between it and other machines readexpiredon both sides.- Every engine on a machine shares one session line. While an engine older than 0.8.8.128 hosts it, a message to another machine is refused and says so; restart that engine.
- The database needs the collections
- The land's guard:
"guard": true(0.8.8.107, off unless the marker sets it). With it,landsends nothing while another session, on this machine or another, is writing a file the land changes; while a folder the land touches is on hold; or while a touched folder whose entry in.oceancode/areas.jsonhas acheckhas not passed that check in this session since its files were last written (the proof is the session's plan record, and what counts as running the check is said in 05; a session without an approved plan has no record and cannot land into such a folder). Each refusal startsNothing landed:and says what to do:this land changes 2 file(s) under crates/x, and that folder's check has not passed in this session since they were last written. Run \./check.sh`, then land again.Without the switchland` sends what it sent in 0.8.8.106. What to know before you set it (0.8.8.108):- The map is the repository's own: the guard reads
.oceancode/areas.jsonfrom Ocean Git at the workspace's base commit, never from the folder, so a session cannot take a check away by changing its copy. A change to the map counts once it has landed. A repository without a map has no checks to ask for, so land.oceancode/areas.jsonon the branch first: until it is there, the hold rule and the check rule pass every land. - An error is never read as "nothing in the way": a map that cannot be fetched or parsed, and a session line that cannot be read, refuse the land and say which.
oceancode workspace landhas no session whose claims and checks it could show, so under the guard the command sends nothing and says so. In 0.8.8.107 the command passed the guard by; do not set the switch on an engine older than 0.8.8.108. What a person pushes with git is Ocean Git's to refuse, not the engine's.- The switch is read where the map is (0.8.8.110): the repository's
.oceancode/ocean-hub.jsonat the workspace's base commit switches the guard on, and so does the folder's own copy; a copy that saysfalsecannot switch the repository's off, and a marker at the base that cannot be read refuses the land. A workspace does not fetch.oceancode/, so for claims across machines copy the marker into the workspace's.oceancode/and give the machine its token. With the guard on and no line to the hub (no token, a marker that could not be used),landrefuses and says why. Up to 0.8.8.109 the switch was read only in the folder, and an engine without a line to the hub sent the land unguarded. - A session can still edit its folder's copy, and a session with a shell can reach Ocean Git without the
engine. So the engine's guard keeps an honest session from a mistake; the fence is Ocean Git's
(
LAND_NEEDS_RECEIPT), which stands once sessions land with an agent's handle. - Claims are per folder. Two Ocean Git workspaces of one repository on one Mac are two folders: a write in one
does not refuse a write to the same repository file in the other, and rule 1 does not see it. Ocean Git's
refusal of a land on a stale base, and
sync, still protect the branch.
- The map is the repository's own: the guard reads
- Where the token goes. The marker may name the hosts (
"url","realtime"), but onlyhttps://plungeai.comor a host under it, or a loopback address (0.8.8.110): this machine's token is sent there, and the marker comes with whatever repository was cloned. A marker naming another host is not used: claims stay on this machine, and the engine's log says why. Another host is the machine's own choice:OC_OCEAN_HUB_URLandOC_OCEAN_HUB_REALTIME(02). - After a gap. When the database has not answered for two minutes (the engine asleep or offline), every write asks it again until the next renewal, within 40 s, has read back which claims it still holds; a file another machine took meanwhile is then refused. Up to 0.8.8.109 the first claim after such a gap made the engine trust all its old claims again (0.8.8.110).
- During an outage. Once a claim found Ocean Base unreachable, the writes of the next 30 s do not ask it again: each goes ahead at once, unprotected, instead of waiting up to 8 s; the renewal still asks every 40 s, and its answer ends the wait (0.8.8.111).
- Machine. One per data dir (an id kept in the line's record), named by its host name. Two engines with one data dir are one machine; their files are kept apart by the session line.
Setting it up, once per repository and once per machine. Create the database from this YAML with
oceancode base apply ocean-hub.yaml (21), which prints its id, and commit
.oceancode/ocean-hub.json naming it. On each machine mint a write token
(oceancode base tokens mint <id> --role write --label <machine>) and keep it in the keychain
(security add-generic-password -s ocean-hub -a <id> -w <token>) or in OC_OCEAN_HUB_TOKEN
(02). Without the file, without a token or without the session line
nothing changes: no tool, no definition and no byte of the system prompt.
kind: database
name: ocean-hub-my-repo
channels: [bell]
collections:
bells: # one row; each claim updates it, and its rule rings `bell`
access: public-read
columns:
owner: user
n: integer required
broadcast:
- topic: bell
on: [update]
private: false
event: bell
sessions: # one row per working session, renewed every 40 s
columns:
id: text
machine: text required
who: text required
doing: text
beat: integer required
claims: # one row per file, slot or named claim; the unique path is the lock
columns:
path: text required unique
session: text required
expires: integer required
taken: integer required
indexes: [session]
plans: # one row per file or folder of a session's approved plan (0.8.8.106)
columns:
session: text required
path: text required
plan: text required
at: integer required
indexes: [session]
lands: # one row per file of a land, heard once by every other machine (0.8.8.107)
columns:
session: text required
who: text required
machine: text required
branch: text required
rev: text required
path: text required
lines: text
at: integer required
holds: # one row per service whose live check failed (0.8.8.107)
columns:
slot: text required unique
session: text required
who: text required
machine: text required
reason: text required
lands: text
at: integer required
kept: # only read with "keep": true: who changed a file last, and its content (0.8.8.107)
columns:
path: text required unique
machine: text required
who: text required
blob: text
at: integer required
drafts: # only read with "draft": true: where a held file's unlanded content is on Ocean Git
columns:
path: text required unique
machine: text required
who: text required
branch: text
tip: text
blob: text
base: text
at: integer required
inboxes: # only read with "messages": true: one row per session that takes messages (0.8.8.127)
columns:
session: text required unique
machine: text required
who: text required
beat: integer required
indexes: [machine]
messages: # only read with "messages": true: a message between sessions on two machines, kept seven days
columns:
from_session: text required
from_machine: text required
from_who: text required
to_session: text required
to_machine: text required
text: text required
state: text required
created: integer required
updated: integer required
heard: integer
indexes: [[to_machine, state], [from_machine, updated]]A database made from an earlier YAML keeps working without lands, holds, kept and drafts: each engine finds out
once that a collection is missing and leaves it alone. Apply the YAML again to add them; no row changes.
Managed (enterprise) config
An administrator can layer a managed config over every project. It is loaded
last, so project < user < managed — managed always wins. Its location is the OS
admin path, or $OC_MANAGED_CONFIG (see
02 · Configuration).
Alongside it, a signed requirements.json carries hard requirements — disabling
bypassPermissions, an MCP-server allow-list, and config pins. It is verified
with ed25519 against the trusted key in $OC_REQUIREMENTS_PUBKEY: an unsigned
or tampered requirements file is refused, never applied. With no key configured,
managed requirements are simply not enforced.
oceancode inspectshows the provenance of every effective config key — which layer (project / user / managed / requirements) set it.oceancode doctorreports crash recovery state: orphaned sessions and captured panic reports. See 07 · Headless and server.
See also
- 02 · Configuration — the config keys and variables.
- 07 · Headless and server —
oceancode doctorand the permission-mode routes.