> ## Documentation Index
> Fetch the complete documentation index at: https://developers.telnyx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Secrets

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](https://developers.telnyx.com/docs/edge-compute/configuration/secrets.md). 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`.

```bash Shell theme={null}
telnyx-edge secrets add OPENAI_KEY "sk-..."
```

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.

```json Request theme={null}
{
  "image": { "ref": "docker.io/library/python:3.12-slim" },
  "network": {
    "rules": {
      "api.openai.com": {
        "headers": {
          "Authorization": "Bearer {{secrets.OPENAI_KEY}}"
        }
      }
    }
  }
}
```

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](https://developers.telnyx.com/docs/edge-compute/sandboxes/common-control-plane/snapshots.md) or [fork](https://developers.telnyx.com/docs/edge-compute/sandboxes/common-control-plane/user-controlled-lifecycle.md#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.

```json Request theme={null}
{
  "image": { "ref": "docker.io/library/python:3.12-slim" },
  "secrets_env": { "DATABASE_PASSWORD": "DB_PASSWORD" },
  "secrets_files": { "/run/secrets/deploy_key": "DEPLOY_KEY" }
}
```

| Field | Shape | Limits |
| - | - | - |
| `secrets_env` | `{"<VARIABLE>": "<SECRET_NAME>"}` | 16 variables, names up to 128 bytes |
| `secrets_files` | `{"/<path>": "<SECRET_NAME>"}` | 16 files, paths up to 1,024 bytes |

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.

> [!WARNING]
>
> A delivered value is in the sandbox's memory and disk. Every snapshot and fork of that sandbox contains it.
