Skip to main content
An HTTP policy controls HTTPS requests from a Sailbox. A policy can:
  • Add, replace, or remove request headers and query parameters
  • Change a request path
  • Send a request to a different HTTPS host
  • Return a response without sending an HTTP request to the destination
  • Add a stored credential to a request
A policy belongs to your organization. You can attach one policy to many Sailboxes, and each Sailbox can have one policy attached at a time. For a guided credential example, start with Credential injection.

​
Write a policy

A policy is a JSON document. Each top-level key selects a host, and each host has an ordered list of rules. This policy adds an API version header to HTTPS requests to api.example.com:
If no host or rule matches, Sail sends the request unchanged.

​
Match a host

Host keys use one of these forms:
  • api.example.com matches that exact host.
  • *.example.com matches any direct subdomain (one label), such as api.example.com. It does not match example.com or one.two.example.com.
  • * matches any host not selected by a more specific entry.
Write the hostname without https://, a port, a path, or a leading dot. Sail selects the most specific host entry and uses only that entry. Host entries do not combine. Use exact hosts when a rule adds credentials. A wildcard sends the credential to every host it matches.

​
Match a request

Add match to limit a rule by method, path, headers, or query parameters:
method is one HTTP method or a list of methods. Matching is exact, so write methods in upper case, such as GET. path and the header and query conditions below accept these matcher forms:
  • A plain string matches that exact value.
  • {"equals": "/v1/models"} is the explicit form of the same exact match.
  • {"prefix": "/v1/"} matches values that start with that text.
  • {"one_of": ["/v1/models", "/v1/files"]} matches any value in the list.
headers and query are lists of conditions, and every condition in the list must hold. A condition can check a name, a value, or both, and "present": false with a name requires that name to be absent:
Sail checks rules from top to bottom and uses the first matching rule. A rule without match covers every request that reaches it, so Sail accepts a rule without match only in the last position of a host’s rule list.

​
Choose what a rule does

A rule can use request, forward, or both. A rule that uses respond cannot also use request or forward. A matching rule with none of these sends the request unchanged.

​
Change a request

Use request.set to replace or create headers, query parameters, or the path. Use request.add to append headers or query parameters. Use request.remove to delete them.

​
Send a request to another host

Use forward with an exact HTTPS hostname:
You can combine forward with request in the same rule. If that request change adds a credential, the host you forward to receives the credential. The request fails if Sail cannot reach that host. It is not sent to the original host instead.

​
Return a response

Use respond when the Sailbox should receive a response without sending an HTTP request to the destination:
Do not use respond as a network access control. It stops this HTTP request, but other traffic to the same host may still be possible.

​
Add a stored credential

Use ${secrets.NAME} in a value under request.set.headers or request.set.query. The named organization secret must exist before you create the policy. Those two fields are templates. Every dollar sign in them must be part of $$ or ${secrets.NAME}, so write $$ for a literal dollar sign. Any other $ is rejected when the policy is created. Every other string in the document treats $ as plain text, with one exception: an unescaped ${ is rejected because it looks like a reference that would not be resolved. These strings have no escape rule. $${ is accepted, and Sail uses those exact characters. A value that needs the exact text ${ cannot be written in these fields. See Credential injection for a complete example and safety guidance.

​
Create and attach a policy

Create a policy once, then attach it to each Sailbox that should use it. The credential injection guide shows the CLI, Python, TypeScript, and Rust creation and attachment calls. Attaching a policy replaces the policy currently attached to that Sailbox. Clearing it leaves the Sailbox with no policy. An attach, replace, or clear affects HTTPS connections the Sailbox opens after the call succeeds. Connections already open keep the previous policy until they close. Close connections your code keeps open if the change must take effect before the next request. A policy document cannot change after creation. Create and attach a new policy to change its behavior. You can rename a policy without changing its rules. If a document is invalid, policy creation fails and the error identifies the part of the document to fix. Sail saves a normalized form of the document. Reading a policy back can return a different shape from the JSON you sent, such as lowercased host names and filled-in defaults. The behavior is the same. For secret updates and the order for removing policies and secrets, see Credential injection.

​
Limitations

  • HTTP policies apply only to HTTPS. Plain HTTP and raw TCP are unchanged.
  • A policy applies to an HTTPS connection only when the client announces its HTTP version while connecting (a TLS feature called ALPN), which almost every HTTP client does. A connection without that announcement passes through unchanged. On an exact host entry, set "missing_alpn": "http/1.1" next to rules to treat such connections as HTTP/1.1. Wildcard and * entries do not accept this key.
  • Request bodies cannot be matched or changed.
  • Responses from a destination cannot be changed.
  • A respond rule stops the matching HTTP request, but it does not block other traffic to the same host.