# Caissons

Read and edit a repository on Sailfork with no local clone, then commit and open a pull request, from the CLI, MCP or the REST API.

## What a caisson is

A caisson is one agent's own working branch of a repository, stored on Sailfork. Writes become blobs on the server and sit over the base commit until you commit them to the caisson's branch. Nothing touches a local disk and no sandbox has to start.

Use a caisson when an agent (or you) needs to change a repository without cloning it. You can run a caisson's tests in a sandbox, covered below.

Opening a caisson needs push access to the repository. Reading one needs read access. A private repository you cannot read answers 404 everywhere.

A file in a caisson is at most 64 MiB.

## Your first caisson

Install the CLI from [the install page](https://status.sailfork.com/install) and sign in with `sailfork auth login`. The command is `sailfork caisson`, with the alias `sf cs`.

```sh
sailfork cs open -R fenil/ocean-landing --title "Fix the tide math" --scope src/tide/
sailfork cs put c-z4nwicj7 src/tide
sailfork cs commit c-z4nwicj7 -m "Fix the tide math"
sailfork cs pr c-z4nwicj7
```

`open` prints the caisson id and its branch, `caisson/<id>` by default. The title is 4 to 200 characters. `put` uploads files and folders, skips files whose content is unchanged, and respects `.gitignore`. Add `--to <prefix>` to upload into a folder of the caisson and `--jobs <n>` (default 16) to change how many uploads run at once.

Other ways to change files:

```sh
sailfork cs write c-z4nwicj7 src/tide/math.rs --file ./math.rs
sailfork cs replace c-z4nwicj7 src/tide/math.rs --old "tide_h" --new "tide_height"
sailfork cs mv c-z4nwicj7 src/tide/old.rs src/tide/new.rs
sailfork cs delete c-z4nwicj7 src/tide/unused.rs
```

`write` also reads stdin with `--file -`, and takes `--create` (only if the file does not exist) or `--if-match <oid>` (only if the file still has the blob you read). `replace` needs exactly one match unless you pass `--all`, and `--regex` and `--dry-run` do what they say. `sailfork cs edit` opens one file in your editor. `sailfork cs diff <id>` shows everything the caisson changed against its base.

`sailfork cs ship <id> -m "message"` commits the uncommitted changes and opens the pull request in one step. It also takes `--closes <n>` and `--refs <n>` to link issues.

More ways to change files:

```sh
sailfork cs insert c-z4nwicj7 src/tide/math.rs --after 12 --text "// tide table"
sailfork cs apply c-z4nwicj7 --patch fix.patch
sailfork cs apply c-z4nwicj7 --file changes.json --dry-run
```

`insert` adds lines after a line number (`0` is the top of the file). `apply --patch` takes a unified diff, such as `git diff` output, and `apply --file` takes a JSON list of changes. Both apply all or nothing, and `--dry-run` prints the result without writing it. `replace` takes `--old` and `--new` more than once for several edits in order. The commands that change files take `--dry-run`.

Start from an existing branch with `--branch <name>`: new commits land on it, so you can continue a pull request's branch. If a stopped caisson left uncommitted edits on that branch, `--carry-edits` copies them into the new caisson. Start from another point with `--base <branch or sha>`. The default branch itself is refused with a 422.

## Scope

The scope lists the paths a caisson may write. Repeat `--scope` for more paths. Each entry is a file path, a folder ending in `/`, or `""` (or `.` in the CLI) for the whole repository. With no `--scope`, the caisson covers the whole repository. A caisson takes 1 to 50 entries.

A write outside the scope is refused with a 403.

The owner of the repository (you, or the organization) also sets path rules that apply to every caisson. A `never` rule refuses the write with a 403 that names the rule. An `ask` rule holds it for a person (see [Writes held for a person](#writes-held-for-a-person)). `sailfork cs open` prints the rules and limits under the new caisson's id; `sailfork cs policy` shows them without opening one.

A new owner starts with these rules:

| Pattern | Rule | Can the owner change it? |
| --- | --- | --- |
| `migrations/**` | ask | No. Schema changes always wait for a person. |
| `.sailfork/**` | never | No. Repository settings change only in a reviewed pull request. |
| `**/*.env` | never | Yes |
| `infra/**` | ask | Yes |

You edit the rules in Settings, Caissons, under Protected paths, where each rule is Ask me or Never. An organization's rules apply to every repository in it, and your own apply to every repository you own.

## Reading and searching

Reads see the base commit with the caisson's uncommitted edits laid over it.

```sh
sailfork cs ls c-z4nwicj7 src/tide
sailfork cs cat c-z4nwicj7 src/tide/math.rs --lines 10-40 -n
sailfork cs grep c-z4nwicj7 "tide_h" src -g "*.rs" -C 2
sailfork cs find c-z4nwicj7 "**/*.test.ts"
```

| Command | Useful flags |
| --- | --- |
| `cat` | `--lines N`, `START-END` or `START-`; `--head N`; `--tail N`; `-n`; several paths in one call |
| `grep` | `-F` plain text, `-i`, `-l` paths only, `-c` counts, `-g <glob>`, `-C`/`-B`/`-A` context, `--limit` |
| `find` | a glob, an optional folder, `--limit` |

`grep` uses Rust regex syntax. Its `--limit` is 1 to 2000 (default 200), and so is the limit of `find`. `-C` allows at most 20 lines of context. `grep` and `find` exit 1 when nothing matched, as grep does. `grep` skips binary files and files over 16 MiB and lists them as skipped.

Beyond text search, these read the caisson's files too, uncommitted edits included:

| Command | What it does |
| --- | --- |
| `cs symbols <id> <query>` | Finds where functions, types and classes are defined. `--kind`, `--path`, `--limit` (default 30). |
| `cs refs <id> <symbol>` | A symbol's definitions and references. `--path`, `--limit` (default 100). |
| `cs ast-grep <id> <pattern> --lang rust` | Searches by syntax. `$A` captures one node and `$$$A` any number. Languages: rust, typescript, tsx, javascript, python, go. |
| `cs ast-rewrite <id> <pattern> <rewrite> --lang rust` | Rewrites every outermost match, all or nothing. A dry run that prints the diff unless you add `--apply`. |
| `cs lsp <id> <op> <target>` | Asks a language server: `definition`, `references` and `hover` take `path:line:column`, `diagnostics` takes a path, `status` takes nothing. |
| `cs lsp-rename <id> <path:line:column> <new name>` | Renames a symbol through the language server, all or nothing. A dry run unless `--apply`. |
| `cs bash <id> '<script>'` | Runs a simulated bash script over the files on the server. No sandbox, no real programs and no network. Writes land all or nothing. |

`lsp` needs the `sandbox` scope and a Drydock host, because the language server runs in a sandbox of yours that starts with your first question and ends 30 minutes after the last. While it starts or indexes, `lsp` answers with a state such as `starting` or `indexing`, so ask again. `--setup` runs a shell command in `/work` first, such as `pnpm install`. `cs lsp-stop <id>` ends your language servers now. `bash` runs a script for at most 30 seconds, and a script is at most 64 KiB; a non-zero exit saves nothing unless you pass `--save-on-failure`.

## Writes held for a person

If a path matches an `ask` rule, the write is held. The server answers 202 instead of 200, and the caisson moves to `waiting`. The write lands only when a person approves it. Other writes keep landing, but only one write is held at a time: a second write to a path under an `ask` rule is refused with a 409 until the first is answered. A batch (`cs apply`, `caisson_batch`) that touches such a path is refused with a 409, so write that path alone.

People who can approve it get a notification, and the CLI exits with code 11 (needs approval). Open the caisson from the notification, read what the write does under Allow the write to, and choose Allow this write or Refuse. A refused write is dropped. To wait for the answer from a script, use `sailfork wait caisson <id> --state editing`.

An agent cannot approve or deny a held write. The approval call refuses access tokens, so only a person in the browser can answer. An agent can withdraw its own held write by restoring that exact path on its own:

```sh
sailfork cs restore c-z4nwicj7 db/migrations/0042.sql
```

Restore is also how you drop any uncommitted change. Pass a file, a folder, or `.` for everything. Restoring `.` discards every uncommitted change and needs `--yes`. `--dry-run` prints the diff it would apply and changes nothing.

## Review before a pull request

An owner can require a review of the exact code a caisson carries before its pull request opens and again before it merges. In Settings, Caissons, under Limits, set Review before a pull request opens or merges to Off, Agent or Independent. Agent counts a review by the opener's own agent, labeled as a self-review on the pull request. Independent needs a review from a different account.

The server holds no model. It hands your reviewer a packet and records the verdict:

```sh
sailfork cs review c-z4nwicj7
sailfork cs review-submit c-z4nwicj7 --head <head> --verdict changes --text "Checked the tide math" --findings findings.json
sailfork cs review-resolve c-z4nwicj7 --finding 3 --text "The test now covers it"
```

`review` prints the diff, risk prompts and a `head`, the tree of the caisson's whole state. Submit with that `head`: any later edit changes it and needs a new review. `--verdict` is `approve` or `changes`, and `--findings` is a JSON list of `{"file", "line", "severity", "scenario"}` with severity `low`, `medium`, `high` or `critical`. An approval with a high or critical finding is refused (422), and `review-resolve` clears a finding. A tree takes at most 10 reviews and a caisson 30. The review is posted on the pull request as its reviewer.

## Caisson settings

Settings, Caissons has the rules for writes that arrive through a caisson, whichever agent or key sends them. Your own settings apply to every repository you own. An organization's apply to every repository in it, and only an owner can change them: open the page with `?org=acme` or from the organization's settings. An access token cannot change them, only a person in the browser, and each change goes in the audit log with the path rule count, the live cap and the idle time.

Choose Save to apply changes, or Discard to drop them. The page refuses a value outside its range and names the problem.

### Limits

The Limits group keeps caissons from piling up unattended.

| Setting | Range | Default | What it does |
| --- | --- | --- | --- |
| Live caissons per repository | 1 to 50 | 8 | Opening one more is refused with a 409 until another is merged or closed. A caisson in `editing`, `waiting` or `review` counts. |
| Close when idle | 15 to 1,440 minutes | 120 | A caisson with no writes for this long stops itself, and its branch is kept. A caisson with a sandbox queued or running, or with an open pull request, stays. A caisson waiting for a person to approve a write stops after 12 times this long, and approvers get a reminder at half of it. |
| Review before a pull request opens or merges | Off, Agent, Independent | Off | See [Review before a pull request](#review-before-a-pull-request). |

The server enforces all three. The page takes a narrower range than the server, which accepts 1 to 64 live caissons and 5 to 1,440 idle minutes.

### Dry run

The Dry run panel on the same page walks one write through the settings as they are now, including edits you have not saved. Type a path, or choose a sample, and it shows each step as does, asks or stops: the write, the commit to the caisson's branch, the pull request and the merge.

The write step follows your Protected paths. A match with Never stops the walk, a match with Ask me waits for a person, and the panel names the rule that matched. The panel changes nothing and checks only path rules. It does not count live caissons or check a review. A merge always follows the repository's branch rules.

## Testing a caisson's code

```sh
sailfork caisson test c-z4nwicj7 --org acme -- cargo test
```

`caisson test` runs a command on the caisson's code, its base plus uncommitted edits, in a throwaway sandbox. It needs a Drydock host that your organization registered. See [Sandboxes and Drydock](https://status.sailfork.com/docs/sandboxes) for setup.

The command exits with the command's own exit code, so a failing test is a non-zero exit and not a CLI error. A command killed by `--timeout` exits 124. Useful flags:

| Flag | Meaning |
| --- | --- |
| `--timeout <secs>` | Kill the command after this long (default 120, at most 3600) |
| `--image <image>` | Sandbox image (default `buildpack-deps:noble-scm`) |
| `--keep` | Leave the sandbox running and print its id on stderr |
| `--sandbox <id>` | Rerun in a running sandbox of this caisson |
| `--wait <secs>` | Wait for a host with room (default 60, at most 600, `0` fails at once) |
| `--affected` | Run only the tests the caisson's changes reach; exits 3 when nothing is affected |
| `--save` | Save what the command changed in `/work` back to the caisson when it exits 0 |
| `--save-on-failure` | With `--save`, also save after a non-zero exit |

## States and stopping

| State | Meaning |
| --- | --- |
| `editing` | Open, with no write held |
| `waiting` | A write is held for a person |
| `review` | A pull request is open |
| `merged` | The pull request merged |
| `stopped` | Stopped by hand or after sitting idle |

List caissons with `sailfork cs list --state <state>` and inspect one with `sailfork cs view <id>`; add `--log` to print its session steps.

```sh
sailfork cs stop c-z4nwicj7 --reason "superseded" --yes
```

Stopping keeps the branch if it has commits beyond the base. `--delete-branch` deletes it too, unless a pull request was opened from it. A repository has a cap on live caissons (`editing`, `waiting` and `review`): 8 unless the owner changes it. A caisson that has no write for 120 minutes (the owner can change that) stops by itself, unless a sandbox of its code is queued or running. One with an open pull request stays until the pull request merges, closes or stops. Opening past the cap fails with a 409 that lists which caissons hold the slots and which are safe to stop. Both limits are under Settings, Caissons, Limits. See [Caisson settings](#caisson-settings).

To try a second approach side by side, `sailfork cs fork <id>` makes a new caisson from the first one's commit and uncommitted edits. A fork counts toward the cap, and a family of forks holds at most 24 caissons, stopped ones included. Edits under a path rule and a held write are not carried. `cs pr` and `cs ship` take `--stop-forks` to stop the live forks that lost when you open the winner's pull request.

Wait for a state from a script with `sailfork wait caisson <id> --state review`.

## Errors you will meet

| What you see | Meaning |
| --- | --- |
| 403 with a rule | The path is under a `never` rule, or outside the caisson's scope. |
| 409 when opening | The repository is at its live-caisson cap. |
| 409 on a write | The caisson is merged or stopped, or another write is already held. |
| 409 on a batch | The batch touches a path under an `ask` rule. Write that path alone. |
| 412 | You sent `--if-match` and the file changed since you read it. Read it again. |
| 413 | A file is over 64 MiB. |
| 422 when opening | A bad title or scope, or the branch is the default branch. |
| Exit code 11 | The write is held for a person. |

## Over MCP

The `caissons` toolset opens a caisson, reads and writes its files, commits and opens the pull request. Tools include `caisson_batch` (many changes at once, or `restore`), `caisson_patch`, `caisson_ship`, `caisson_test`, `caisson_review` and the search tools `caisson_grep`, `caisson_glob`, `caisson_symbols`, `caisson_ast_grep` and `caisson_lsp`. Start the stdio server with `sailfork mcp`, or pick toolsets with `--toolsets`. See [MCP server](https://status.sailfork.com/docs/mcp) for connecting a client.

## Over the REST API

Every step above has a route under `/api/orgs/{owner}/caissons`. A file write is `PUT .../caissons/{id}/files/{path}` with the raw bytes in the body, at most 64 MiB. See [the REST API](https://status.sailfork.com/docs/api#caissons) for the list.

---

Every docs page: https://status.sailfork.com/llms.txt
