> ## Documentation Index
> Fetch the complete documentation index at: https://www.plungeai.com/guide/llms.txt
> Use this file to discover all available pages before exploring further.

# Permissions and sandbox

> Ocean Code decides what a tool may do in three layers, from softest to hardest:


Ocean Code decides what a tool may do in three layers, from softest to hardest:

1. **Permission rules and modes** — an ask/allow/deny policy over each tool call.
2. **The shell and filesystem guards** — a classifier that reasons about what a
   `bash` command or a file edit actually does, on top of the rules.
3. **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](/oceancode/cli-reference#oceancode-workspace)).
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](/oceancode/configuration)), or switch it live over the HTTP API
(see [Switching the mode live](#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](/oceancode/tui#shifttab-ring-and-permission-modes)).

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](/oceancode/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](/oceancode/jev-decisions#what-jev-decides)). 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](/oceancode/mcp#held-until-trusted)).

### 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](/oceancode/headless-and-server#permission-mode)). 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: `find` with `-delete`, `-exec`, `-execdir`, `-ok`, `-okdir`, `-fprint`,
  `-fprint0`, `-fprintf` or `-fls`; `git branch` that deletes, renames, copies,
  forces or re-points (`-d`, `-D`, `-m`, `-M`, `-c`, `-C`, `-f`, `-u`, `--delete`,
  `--set-upstream-to`, `--unset-upstream`); `git remote` with `add`, `remove`,
  `rm`, `rename`, `set-url`, `set-head`, `set-branches`, `prune` or `update`; and
  `git tag` that creates, signs, forces or deletes (a name after `tag` creates a
  tag unless `-l`/`--list` makes 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,
  and `curl … | sh`. The floor peels wrappers and unwraps `bash -c`/command
  substitutions, so hiding the command behind `sudo`, `/bin/rm`, or `$(…)` does
  not evade it.
- **`shell` overrides.** `safe_list_extra` adds read-only commands; `allow` /
  `deny` layer `Tool(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` |

- `deny` lists roots refused even inside the workspace (e.g. `.git`, a secrets
  dir).
- `network` is `off` (no egress) or `allowlist`. **The allow-list is not
  enforced yet:** on macOS and Linux an `allowlist` policy leaves egress open,
  because no child's traffic is routed through the TLS-SNI relay. Use `off` to
  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:

- **`.env` is never read.** `read` refuses `.env` and `*.env` / `*.env.*` files
  (secrets); `.env.example` still reads.
- **Read-before-write.** `write` refuses 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 a `bash` command 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.** `edit` and `write` refuse 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 a `bash` command 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](/oceancode/session-ledger-and-export#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 (`expired` in the log) and their cards read `crashed`, 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_patch` and `hashline` claim 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 (`released` in 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`
  (`blocked` in the log; the session's row reads `blocked` until its next write
  succeeds). The time is how long ago that session last wrote the file (or, for
  a `claim`, took it). `apply_patch` checks 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 `claim` tool.** `claim` holds 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; `release` lets it go. It covers what a script writes inside `bash`, which the
  file tools never see.
- **Your override.** `/peers take <path | name:label>` in the TUI gives the
  claim to your session (`overrode` in the log). It becomes a claim of your
  session's turn, whatever time a taken `claim` had 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 a
  `bash` command runs, the engine claims every slot the map names for it, as
  `name:<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 says `slot_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 first `bash` result.
  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_refused` in 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's `live` command 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 a `hold` row 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 `land` from an Ocean Git workspace logs one
  `landed` row per file (`1111aaaa2222 on main`, with `rebased` when Ocean Git
  applied it on top of a branch that had moved). A land that was refused logs
  `land_refused` for each file it ran into: `conflict on main at <head>`,
  `rejected <status>: …`, or `guard: …` (below). `oceancode peers card` counts
  them ([21](/oceancode/cli-reference#oceancode-peers)).
- **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 `bash` command 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.`, `overwrote` in 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 as `wrote` `by a command`
  when 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 of
  `cp`, `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
  logged `overlap`. 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
  to `done` or `abandoned` (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 repository `wrangler.jsonc` and `worker-configuration.d.ts`, made by
  `npm run update-config`) is refused by `write`, `edit`, `apply_patch` and
  `hashline`, 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_patch` and `hashline` refuse a file that changed
  since the session read it, with the words `edit` uses, naming the session that
  changed it when there is one.
- **Who reads and writes where.** Every write logs `wrote` with the lines it
  changed (`lines 12-14`, `new file`, `deleted`; `oceancode peers log` shows
  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 an `at:` 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 `unprotected` once the store answers again, and the board shows that
  session as `unprotected` for ten minutes.

The map's slot lines, for one area and one slot at the top:

```json
{
  "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_session` tool (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](/oceancode/tui#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 in `paths` matches 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 shows `r12 delivered to #f2k1` once the
  receiving window has the request (2026-11-18; right after a `/message` it reads
  `Sent r12 to #f2k1 · delivered`), then `r12 accepted in #f2k1`, then `done` when
  the turn that ran the request's prompt finishes, or `stopped` when 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 reads `declined`. The `sessions` tool 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 status`
  lists 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/tui#session-peers)); `oceancode peers` lists them and
`oceancode peers log` prints the history ([21](/oceancode/cli-reference#oceancode-peers)).
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:

```json
{ "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 `⇄N` chip.
  - 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 `/messages` and Tab) still lists them when you open it.
- **`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_session` answers `Requests 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](#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](/oceancode/configuration#config-file-locations-and-precedence)).

### 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](/oceancode/headless-and-server#messages-between-sessions-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:

```json
{ "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_from` applies 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](https://base.plungeai.com) 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 an `unprotected` row.
- **Hearing the others.** Every claim updates the database's one-row collection `bells`, whose broadcast rule
  rings the public topic `bell` on 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 `bash` command takes and a `claim` of `name:<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 the `claim` tool 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 `plans` with 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 without `plans`
  (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 peers` lists a session on another machine as `#ab12 on mac-2` with 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 `blocked` row against `hub:<session>` with the note
  `remote`, and the refused session reads `blocked` on 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 collection `lands` (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 `holds` with 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 without `holds` still 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":
  true` in `.oceancode/ocean-hub.json`, the collection `kept` names 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 collection `drafts` names 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 once `src/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 of `keep` stays: 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 `land` asks 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_HANDLE` and that handle's token (the keychain
    item `ocean-git/<handle>`, else `OC_OCEAN_GIT_TOKEN`). Without them the machine sends and takes no draft
    and behaves as with `keep` alone.
- **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 (tagged `other machine`), `/message #f2k1 <text>` and
  `POST /messaging/send` reach 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 `inboxes` and `messages` (in the YAML below; add them to a database you
    already have with `PUT /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_from` names 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_session` stays 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 reads `expired` on both machines.
  - `peers.machines` off stops it with the rest: this machine's sessions leave the list, and the open messages
    between it and other machines read `expired` on 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 land's guard: `"guard": true`** (0.8.8.107, off unless the marker sets it). With it, `land` sends
  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.json` has a `check`
  has 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](/oceancode/plan-mode-and-todos); a session without an
  approved plan has no record and cannot land into such a folder). Each refusal starts `Nothing 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 switch `land` 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.json` from 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.json` on 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 land` has 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.json` at the
    workspace's base commit switches the guard on, and so does the folder's own copy; a copy that says `false`
    cannot 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), `land` refuses 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.
- **Where the token goes.** The marker may name the hosts (`"url"`, `"realtime"`), but only
  `https://plungeai.com` or 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_URL` and
  `OC_OCEAN_HUB_REALTIME` ([02](/oceancode/configuration)).
- **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](/oceancode/cli-reference#oceancode-base)), 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](/oceancode/configuration#environment-variables)). Without the file, without a token or without the session line
nothing changes: no tool, no definition and no byte of the system prompt.

```yaml
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](/oceancode/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 inspect` shows the provenance of every effective config key — which
  layer (project / user / managed / requirements) set it.
- `oceancode doctor` reports crash recovery state: orphaned sessions and captured
  panic reports. See [07 · Headless and server](/oceancode/headless-and-server).

## See also

- [02 · Configuration](/oceancode/configuration) — the config keys and variables.
- [07 · Headless and server](/oceancode/headless-and-server) — `oceancode doctor` and
  the permission-mode routes.
