Documents
A policy is a JSON document with these optional fields:
An entry in
allowlist or blocked is a hostname (api.github.com), a
wildcard for every host below a domain (*.github.com matches
api.github.com and a.b.github.com but not github.com), an IPv4 address,
or an IPv4 range (203.0.113.0/24). A hostname entry allows every kind of
connection to that host, including SSH and plain HTTP.
Let the Sailbox reach only package registries and GitHub:
${secrets.GITHUB_TOKEN} names a secret stored with Sail. The Sailbox never
sees its value, and a document that references a secret must be
saved before a Sailbox can use it.
Credential injection walks through that flow.
No egress and no network
{"allowlist": []} stops every outbound connection but Sail’s own API host.
{"no_network": true} also stops inbound ones.
- No egress,
{"allowlist": []}, also stops every other name lookup. You can still expose a port or use SSH. - No network,
{"no_network": true}, is for work that should have no network at all. It cannot be combined with other fields or set on a Sailbox that exposes a port or SSH. Running commands, the shell, and mounted volumes keep working. - Sail’s own API host,
sailbox-api.sailresearch.com, stays reachable under no egress and under every allowlist, so a Sailbox can always call Sail about itself, for example to reboot. Only no network removes it.
Setting a policy
Pass a document, or a saved policy, asegress_policy
when you create a Sailbox (egressPolicy in TypeScript). Each SDK builds the
common documents for you: allow_all() is {}, allow_only(...) is a
document with only an allowlist, no_egress() is {"allowlist": []}, and
no_network() is {"no_network": true}.
- A document that breaks a rule in the reference fails the call, naming the entry to fix, before a Sailbox is created.
no_networkcannot be combined withingress_ports; the other documents can.- A checkpoint records the policy its Sailbox had when the checkpoint was taken. A Sailbox created from the checkpoint starts with that policy, even if the source’s policy changed later. After that the two are independent.
- A checkpoint of a Sailbox with a saved policy refers to that policy by id, so a Sailbox created from it uses the policy’s current secret values. A checkpoint of a Sailbox with an inline document keeps its own copy of the document.
Replacing the policy
set_egress_policy replaces a Sailbox’s policy and returns the new one.
clear_egress_policy removes all restrictions and rules.
- The new policy applies to connections opened after the call. Connections
that are already open keep the previous policy until they close, except
under
no_network, which stalls them until a later policy restores network access. - A sleeping or paused Sailbox takes the new policy when it next runs.
no_networkis refused while the Sailbox exposes ports or SSH.
Reading it back
Every Sailbox reports the policy it runs under: the document in force, plus the id and name of the saved policy it came from. The handlecreate returns
does not carry the policy; fetch the Sailbox to read it.
Saved policies
A document passed straight to a Sailbox belongs to that Sailbox alone. A saved policy is a document stored under a name for your whole organization. Save a policy to reuse it across Sailboxes or to use secrets in its rules. Only a saved policy can reference a secret, and the secret must exist first.- A saved policy’s document cannot be edited, only its name. To change behavior, save a new policy and set it.
- Deleting a policy fails while a Sailbox that is not terminated uses it, or while a checkpoint that can still start a Sailbox recorded it. Give those Sailboxes another policy, and delete those checkpoints, first. Terminating a Sailbox releases its policy, but its checkpoints keep theirs.
- The listing shows how many Sailboxes and checkpoints use each policy and which secrets it names. A checkpoint shows the id and name of the saved policy it recorded, and the checkpoint list can be filtered by policy.
Blocked
blocked removes destinations from what the Sailbox may otherwise reach.
Each entry must be narrower than what covers it: a hostname under a *.
wildcard in the allowlist, or an address inside an allowed range. Without an
allowlist, only addresses and ranges can be blocked. Sail’s own API host,
sailbox-api.sailresearch.com, cannot be blocked. The
reference has every accepted
form.
Rules
rules maps a host to the rules for the HTTPS requests the Sailbox sends to
it. A rule can change the request, forward it to another host, or answer it.
Plain HTTP and other traffic pass through untouched.
- Hosts are exact (
api.example.com), a wildcard for every host below a domain (*.example.com), or*for every host not named elsewhere. Use an exact host whenever a rule adds a credential. - No rule applies to Sail’s own API host,
sailbox-api.sailresearch.com, not even under*. - A rule does not make its host reachable. With an allowlist, every host that has rules must also be allowed by it.
matchnarrows a rule bymethod,path,headers, orquery. A rule withoutmatchcovers every request and must be last in its list.
missing_alpn, and
the other details are in
the reference.
A saved policy can also give commands
environment variables that
stand in for secrets, and tls_config sets the
certificates Sail uses
to connect to a host.