Try it
This stores a secret, injects it as a bearer token on requests tohttpbin.org, and asks httpbin to echo the request back. Save the policy as
demo.json:
demo.json
Output
curl inside the Sailbox never saw the token. Only the request that
httpbin received included it.
The same flow from the SDKs, with a GitHub token:
Secrets
A secret is a named value that belongs to your organization. Egress policies insert secrets into requests, and registry logins use them to pull private images._, and -, up to
128 characters. A value is non-empty text up to 64 KiB. It may span lines, as
a PEM key does, but cannot contain tabs or other ASCII control characters.
Policies
A credential is added by a rule in an egress policy. The rule specifies the host, optionally narrows the requests it applies to, and sets a header, query parameter, or body field to${secrets.NAME}. The
reference has the full document
format.
- Only a saved policy may reference a secret, and the secret must exist before the policy is saved. A document passed straight to a Sailbox cannot use one.
- Use an exact host. A wildcard such as
*.example.comsends the credential to every host it matches.
allowlist, so one policy limits a Sailbox
to the hosts it needs and adds their credentials. A saved policy’s document
cannot be edited. To rotate which hosts get a credential, save a new policy
and set it. To rotate the credential itself, set the secret again.
Clients that need a key
Some clients refuse to start without an API key in the environment, or read the key themselves to build the request. For these, the policy’senv gives
every command in the Sailbox a placeholder in place of the key, and a
request.replace rule swaps it for the real key on the way out:
$OPENAI_API_KEY holds a value like
sail_ph_3kTq9.... The OpenAI client sends it as
Authorization: Bearer sail_ph_3kTq9..., and the request reaches
api.openai.com with the real key. The placeholder is useless anywhere else:
Sail refuses a request that carries it in a field the policy does not name,
so code in the Sailbox cannot move it into a URL or another header to get the
key sent somewhere unexpected.
An agent that acts for several people can hold a key for each of them. Give
each key its own env variable, and map the header to a list of the secrets,
as in "authorization": ["NOTION_ALICE", "NOTION_BOB"]. Sail sends the key
whose placeholder the request carries. See
Several keys for one host for a full
policy.
For a client that checks the shape of a key, choose the placeholder’s start
with {"secret": "OPENAI_KEY", "placeholder_prefix": "sk-"}. See
Environment variables for the full rules.
AWS and S3-compatible storage
AWS and S3-compatible storage do not take a key in a header. The client uses its secret key to sign each request, so there is no field for a rule to fill in. For these, name a cloud identity in the policy, and Sail signs the request on the way out:aws identity:
Private servers and client certificates
tls_config connects to a host that uses a private certificate authority, or
that asks for a client certificate (mutual TLS). Store the client
certificate’s private key as a secret, then name it in the policy:
https://mtls.example.com as usual. Sail
checks the server against trusted_cas and presents the client certificate,
and the private key never enters the Sailbox. See
TLS settings for each field.
Giving a Sailbox the policy
Give the same saved policy to as many Sailboxes as you like.Where secrets live
Secrets are stored by Sail and added as the request leaves the Sailbox. Nothing inside the Sailbox ever sees the value, and no Sail API returns it:sail secret show and sail secret list print names and timestamps only.
Output
sail egress-policy list shows how many Sailboxes use each
policy and which secrets it names.