Storing Secrets
Sandboxes use the same secrets as Edge Compute functions. A secret is created, updated, and deleted withtelnyx-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
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
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.commatches that name only. - Wildcards.
*.example.commatches every name belowexample.comat any depth, neverexample.comitself. - Ports. A rule applies to TLS on port 443 only. Plain HTTP and other ports receive no header.
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 andProxy-*headers cannot be set.- HTTP/1.1, HTTP/2, gRPC, and WebSocket requests all receive the header.
Validation
Every secret a rule names must exist when the sandbox is created. A missing one is refused with422 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.crtand 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, andBUN_CA_BUNDLE_PATH.
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.