Caisson isolation
What one agent's caisson can see of another's, what happens when writes collide or stop halfway, and what a script or build can reach, as the server enforces it today.
This page says what the server does, not what it is meant to do. Where a control does not exist, the page says so. For how to use caissons, see Caissons. For the routes, see the Caissons API.
What a caisson is in storage
A caisson is a row in the server's database plus an overlay of uncommitted edits.
- The row holds the repository, the account that opened it, the token it was opened with (the token's name stays after the token is deleted), its branch, the commit it started from, its scope, its state and the one held write, if any.
- The overlay has one row per changed path: the file's blob id, mode and size, or no blob for a deletion. A file of 256 KiB or less keeps its bytes in the database row until you commit. A larger file is written to the repository's object storage when you write it, and the row points to it.
- The session log has one entry per open, read, edit, commit, pull request, held write and stop, and per
bashrun. Abashentry keeps the first part of the script and the last 4 KiB of its output.
Nothing touches the branch until a commit. While a caisson is live, its reads show the branch's current tip with the overlay on top, so a push by someone else to the same branch shows up in the next read.
A caisson never writes to a disk the agent can reach. Its files are rows and blobs on the server.
Who can read and write a caisson
Opening a caisson makes you its opener. It does not make the caisson private to you.
| Action | Who can do it |
|---|---|
| Read a caisson, its files, its diff and its session log | Anyone who can read the repository: a person with read access, or anyone signed out for a public repository. A token needs repo:read, and a token limited to other repositories gets 404. |
| List caissons | The same people see every caisson of every repository they can read. The list for a screen (brief) also shows the paths each live caisson has read. |
Write a file, run bash, commit, open the pull request, stop | The key that opened it, its opener in the browser, or an administrator of the repository. Anyone else with push access gets 403 caisson_held_by. A token with branch limits must also match the caisson's branch. |
| Fork | Anyone with push access and repo:write: a fork only reads the source caisson. |
| Answer a held write | A person with push access, in the browser. A token cannot. |
| Start a sandbox from a caisson's code | Anyone who can read the repository and has the sandbox scope. See Sandboxes from a caisson. |
Some consequences follow from this:
- Another agent can read yours. Another agent on the same repository can read your caisson's uncommitted edits, the scripts you ran and the paths you read.
- Another agent cannot change yours. A second token with push access gets 403
caisson_held_byon a write, commit, pull request or stop, and opening your caisson's branch with--branchis refused the same way. Only the key that opened it, its opener in the browser, or an administrator of the repository can change it. A caisson opened in the browser, or whose key was deleted, belongs to its opener with any of their keys. - Opening a branch that already has a live caisson returns that caisson.
open --branch featureon a branch another caisson is working on does not start a second one. You get the first caisson back, with its own title and scope, and your writes land in it. Passing--scopewidens that caisson's scope, and only a holder of it can. - Directory rules still apply. A repository that hides directories from a reader hides them in a caisson too, in reads, searches, scripts and sandboxes. A reader who cannot read the whole tree cannot start a sandbox from it.
- A token limited by paths cannot commit. Path limits on a token are checked only on
git push, and such a token may move no branch any other way. It can still write to a caisson's overlay, but its commit is refused.
A private repository you cannot read answers 404 on every caisson route.
Concurrent writes
| Situation | What happens |
|---|---|
| Two writes to one caisson at once | The server locks the caisson's row for each write, so they apply one after the other. The last write to a path wins unless the writer sent If-Match with the blob it read (--if-match in the CLI). Then a stale write is refused with 412. replace and insert compare the blob they edited and answer 412 when it changed under them. |
| A batch, a script or a sandbox save | All or nothing, in one transaction, with the path rules checked for every path first. A bash run saves nothing when the caisson changed while the script ran. |
| Two caissons on different branches | They do not touch each other. Their pull requests meet at merge, under the repository's merge rules. |
| Two agents on one branch | They share one caisson. See above. |
| The branch moves before you commit | The next write or commit adopts the pushed commits: head_sha moves to the tip and the session records one pull step with how many commits arrived (the caisson's adopted count). The commit builds on the tip. A file the caisson edited before the adoption and the pushed commits also changed is not replaced silently: the commit is refused with 409 naming the paths. Restore a path to take the pushed version, or read it and write it again. Files the caisson did not edit stay as the branch has them. The server does not merge. |
| The branch moves during the commit | The branch moves only by compare-and-swap. The commit is refused with 409, moved while committing; the edits are kept, commit again, and the overlay stays. |
| Opening past the cap | Opening takes a lock per repository, so two opens at once cannot both pass the live-caisson cap. |
To avoid losing another commit's edits, read the file again and send If-Match on the write, or compare the diff before you commit.
Interrupted writes
| What stops | What is left |
|---|---|
| A write fails before it commits | Nothing. A small file's bytes and the overlay row are written in the same transaction. A file over 256 KiB is stored before the transaction, so a failure there leaves an unreferenced object in the repository's storage and no overlay row. |
| A batch fails partway | Nothing. It is one transaction. |
A bash script is killed, crashes or hits a limit | Nothing, unless you passed saveOnFailure and the script finished. |
| A commit fails before the branch moves | The overlay is kept and the branch is unchanged. Objects the commit stored stay unreferenced. |
| The server stops after the branch moved and before the overlay was cleared | The next commit finds the edits already match the branch, clears them and answers 409, nothing to commit. Nothing is lost or applied twice. |
| An agent disappears with a write held for a person | The caisson stays waiting. Approvers are reminded once at half of the owner's idle time. After 12 times the idle time the server stops the caisson and drops the held write. |
| An agent disappears with edits not committed | After the owner's idle time (120 minutes by default) with no write, the caisson stops and its branch is kept. The overlay is kept too, and open --branch <branch> --carry-edits copies it into a new caisson. A caisson with a sandbox queued or running, or with an open pull request, is not stopped for idleness. |
A sweep runs every 15 seconds and stops idle caissons, reconciles merged ones and tells the opener when it stops one.
Caisson bash
caisson bash is an interpreter, not a shell on a machine. It runs on the Sailfork server, with no Drydock host and no sandbox.
- What it runs. Each script runs in its own short-lived process that interprets the script and starts nothing. Pipelines, loops and the common text commands are simulated. There are no real programs, so no compiler and no test runner. Use
caisson testfor those. - Files. The script sees a file system made of the caisson's files at
/work, and a scratch area that is thrown away. It sees only paths the caller may read. It cannot name a path outside that listing, and nothing on the server's disk is visible. - Network. None. On Linux the process is limited to a short list of system calls, so opening a file, a socket or another process fails, and it holds no inherited descriptors or privileges.
- Limits. 30 seconds of wall time, 100,000 commands, a script of 64 KiB, 256 MiB of memory for the interpreter and 512 MiB of address space, 1 GiB read and 128 MiB written in one run. At most 4 scripts run on the server at once and 2 per owner. A script past a limit exits 124.
- What it changes. The parent process, not the script, saves the changes. They go through the batch path under your scope and path rules: a
neverpath refuses the whole run, and a change to one path under anaskrule is held for a person. A change that touches anaskpath together with others is refused. - What it leaves behind. The first 4 KiB of the script and the last 4 KiB of its output are written to the session log, which anyone who can read the caisson can read.
Sandboxes from a caisson
caisson test, caisson_test, a sandbox started with --caisson and a language server run in a sandbox on a Drydock host. The commands you run there are real programs. A build script or a test is arbitrary code.
| Question | Answer |
|---|---|
| Whose machine? | A Drydock host your organization registered, or a cloud machine it connected. Whoever runs that machine can see everything in the sandbox. |
| What contains the code? | A container under gVisor on that host. A host started with --isolation container runs plain containers instead, and an organization can refuse such hosts. |
| What does it start with? | The caisson's whole tree with its uncommitted edits, packed once and fetched from a short-lived link. No Sailfork token or other credential enters the sandbox. |
| Which network? | outbound unless the organization says none. caisson test has no option to ask for none. Outbound reaches the internet but not private networks, cloud metadata addresses or the host itself, and refuses mail ports 25, 465 and 587. A host started with --allow-private-egress lifts the private-network rule. |
| Which secrets? | For an organization's sandbox, the organization's sandbox secrets that are granted to the caisson's repository, as environment variables. A personal sandbox gets none. |
| Are secrets hidden? | Output shows *** where it would print a secret's exact value. That is a courtesy, not a control: a script can print the value in another form, or send it to any address that outbound reaches. |
| Who can start one? | Anyone with the sandbox scope who can read the repository, in an organization they belong to, including from another agent's uncommitted caisson. Push access is not needed. |
| How long does it live? | Until it exits or its minutes run out (60 by default), and caisson test destroys it when the command ends unless you pass --keep. A failed destroy leaves it until it expires. |
| What persists? | A caisson's workspace volume on the host, so a second test starts with the first one's build output. It is private to that caisson and person, and --fresh-workspace throws it away. |
| Can it change the caisson? | Only with --save, which writes what the command changed in /work back through the batch path, under the same scope and path rules. |
A build script in the sandbox can read every file in the caisson's tree and every secret granted to the repository. It can reach the internet when the network is outbound. It cannot reach your private networks or the host's other services, and it cannot reach Sailfork with any credential of yours.
To keep secrets away from unreviewed code, grant them only to repositories whose caissons you trust, or run tests with network none by setting it for the organization.
Path rules, held writes and undo
Each repository owner (you, or the organization) has path rules. A path matches never, ask or no rule, which allows it.
| Rule | Effect on a caisson write |
|---|---|
never | 403 naming the rule. The whole batch or script run is refused. |
ask | The write is held, the server answers 202, and the caisson waits. Only one write is held at a time per caisson. |
| none | The write lands. |
- First match. The first rule in the list that matches a path applies.
- Fixed rules.
.sailfork/**isneverandmigrations/**isask, and a policy that drops or changes either is refused. The server checks that both are present, not that they come first, so a rule listed above one decides for the paths it matches. - Who changes the rules. An organization's rules change only in the browser, by an owner, and are audited. A person's own rules apply to repositories they own and can be changed with a token that has the
userscope. - Held writes. The write waits until a person with push access answers in the browser. A token cannot answer, so an agent cannot approve its own write. The person who opened the caisson can approve it from their own browser session. Restoring that exact path withdraws the write. A refused write is dropped.
- Undo.
sailfork undotakes back one action within 24 hours. The kinds are issue and pull request comments, edits to issues and pull requests, a merge, a deleted file in a caisson, a deleted branch and a created token. Writing a file, committing and opening a pull request are not on the list.
What is not a control
- Path rules only guard caisson routes. A token with
repo:writecan change the same paths withgit pushor the single-file commit route. Branch rules and protected paths govern those, and they are separate. - Agent identity is a label. The
X-Sailfork-Agent,X-Sailfork-SessionandX-Sailfork-Surfaceheaders say what tool made a request. Any holder of a token can send any value or leave them out. The label is for reviewers and plan counts, and it proves nothing. - A signature shows the route, not the agent. A caisson commit has the account's name and a
handle@users.sailforkaddress as author and committer, is signed by the server with an SSH signature, and ends withSailfork-Caisson,Sailfork-TokenandSailfork-Agenttrailers. The signature says the commit came through a caisson; the token name and agent label in the trailers are labels the token holder controls. - Masked output is not secrecy. See Sandboxes from a caisson.
- A caisson is not private. See Who can read and write a caisson.
Threat model
| Threat | What stops it | What does not |
|---|---|---|
| An agent writes to a sensitive path through a caisson | A never rule refuses it and an ask rule holds it for a person. The two fixed rules always exist. | git push and the single-file commit route do not read path rules. A rule listed above a fixed rule decides first. |
| An agent approves its own held write | Tokens are refused on the answer route. | A person at the same account, in a browser, can approve. |
| Another agent reads or changes an agent's caisson | Changes are for the key that opened it, its opener and repository administrators; reads need read access; a token's repository and branch limits. | Anyone with read access can read any caisson on that repository, its log included. |
| Two agents overwrite each other | Separate caissons are separate branches. If-Match refuses a stale write. A branch moved during a commit is refused. | A commit over a branch that moved earlier replaces the files it edited, with no merge. Two agents on one branch share one caisson. |
| A write dies halfway | Transactions: a write, a batch or a script run is all or nothing. A failed commit keeps the overlay. | A large file stored before a failure stays in storage as an unreferenced object. |
| An agent runs code on the server | caisson bash starts no process and has no network or disk, with time and memory limits, and on Linux a short list of system calls. | The script and its output stay in the session log for every reader. |
| A build script reads secrets | Secrets reach only sandboxes of the organization they belong to, for repositories they are granted to. | Any code in such a sandbox can read them and, on an outbound network, send them out. Masking is an exact-match filter. |
| A build script reaches private networks or the host | The egress firewall on the host, which refuses to start when it is not intact. | A host started with --allow-private-egress, which an organization can refuse. |
| A build script escapes its container | gVisor on the host. | A host running plain containers, which an organization can refuse. |
| An agent forges who it is | Nothing. | Identity headers are labels. |
| An agent's commits cannot be traced to it | The caisson records the token that opened it and the session log records its steps. | The trailers name the token, but a holder of the token can send any agent label. |
| Caissons pile up unattended | The live-caisson cap and the idle sweep. | Nothing stops one agent from using the whole cap. |