Skip to main content
A secret rule lets code in a sandbox use a credential without the sandbox ever holding it. The host adds the value to outbound HTTPS requests on the sandbox’s behalf.

Storing Secrets

Sandboxes use the same secrets as Edge Compute functions. A secret is created, updated, and deleted with telnyx-edge secrets or at https://api.telnyx.com/v2/compute/secrets. Names are stored in upper case, so a secret created as openai_key is referenced as OPENAI_KEY.
Shell
A value is used up to 64 KiB.

Secret Rules

network.rules on the create maps a host to the headers the platform sets on HTTPS requests to it. A header value is a template with {{secrets.<NAME>}} markers.
Request
Code in the sandbox sends a normal HTTPS request to api.openai.com. The host terminates TLS for that host, sets the Authorization header with the value, and forwards the request. The sandbox’s code, environment, files, and snapshots never contain the value.

Hosts

  • Exact names. api.openai.com matches that name only.
  • Wildcards. *.example.com matches every name below example.com at any depth, never example.com itself.
  • Ports. A rule applies to TLS on port 443 only. Plain HTTP and other ports receive no header.
A rule’s host is reachable under the allowlist egress mode without an allow_out entry. Rules are refused under blocked with 422 rules_not_allowed.

Headers

  • A rule’s header replaces any header of the same name the sandbox sent.
  • Every marker in a header must resolve. Otherwise the platform omits the header, removes the sandbox’s header of the same name, and still forwards the request.
  • Host, Content-Length, Transfer-Encoding, Connection, and the hop-by-hop and Proxy-* headers cannot be set.
  • HTTP/1.1, HTTP/2, gRPC, and WebSocket requests all receive the header.
A rule names at most 32 hosts with at most 16 headers each. A template is at most 2,048 bytes. Rules are fixed at create, and a snapshot or fork copies them.

Validation

Every secret a rule names must exist when the sandbox is created. A missing one is refused with 422 unknown_secret. When the platform cannot read the organization’s secrets, the create is refused with 503 secrets_unavailable and a Retry-After header.

Updates

An updated value reaches a rule’s headers within about a minute, with no restart. A deleted secret’s header is omitted from then on.

Trust

A sandbox with rules receives its own certificate authority, limited to the rules’ hosts. The sandbox trusts it from its first instruction.
  • System bundle. The CA is appended to /etc/ssl/certs/ca-certificates.crt and written to /etc/ssl/certs/sandbox-egress-ca.pem.
  • Client variables. Every sandbox’s environment, with or without rules, points common clients at the bundle with SSL_CERT_FILE, CURL_CA_BUNDLE, REQUESTS_CA_BUNDLE, PIP_CERT, NODE_EXTRA_CA_CERTS, NODE_USE_SYSTEM_CA, NPM_CONFIG_CAFILE, GIT_SSL_CAINFO, AWS_CA_BUNDLE, CARGO_HTTP_CAINFO, GRPC_DEFAULT_SSL_ROOTS_FILE_PATH, DENO_CERT, and BUN_CA_BUNDLE_PATH.
A client that pins the destination’s certificate, or uses its own trust store such as a JVM keystore, fails the handshake to a rule host. Containers started inside the sandbox do not inherit the trust.

Placeholders

A {{secrets.<NAME>}} marker in the create’s env, or in an exec’s env, becomes a placeholder, a random string that stands in for the value. It lets a client that refuses to start without the variable set run as usual. The host sets a rule’s header from the rule itself, whatever the code sent, so no request needs the placeholder. A placeholder sent to any other host, or copied out of the sandbox, is a worthless string.

Delivery into the Sandbox

Some credentials cannot travel in an HTTPS header, such as a database password, an SSH key, or a client certificate. secrets_env and secrets_files deliver a secret’s value into the sandbox.
Request
Delivered values total at most 128 KiB per sandbox. A delivered value is read when the sandbox is created and does not change when the secret is updated.
A delivered value is in the sandbox’s memory and disk. Every snapshot and fork of that sandbox contains it.