Skip to main content
An egress policy limits which hosts a Sailbox can connect to, and can add credentials to the HTTPS requests it sends. A Sailbox gets its policy when it is created and can be given a new one at any time. Without one, it can reach any host.

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:
Reach GitHub and every host below it, except Gist:
Reach GitHub and add a token to every request sent to its API:
${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, as egress_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_network cannot be combined with ingress_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_network is 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 handle create 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.
  • match narrows a rule by method, path, headers, or query. A rule without match covers every request and must be last in its list.
Each action’s fields, templates, forwarding failures, 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.