Environment Variables & Secrets

prime sandbox create python:3.11-slim \
  --env APP_ENV=staging \
  --env LOG_LEVEL=debug \
  --secret API_KEY=sk-abc123 \
  --secret DB_PASSWORD=hunter2

sandbox = client.create(
    CreateSandboxRequest(
        name="configured-runner",
        docker_image="python:3.11-slim",
        environment_vars={"APP_ENV": "staging", "LOG_LEVEL": "debug"},
        secrets={"API_KEY": "sk-abc123", "DB_PASSWORD": "hunter2"},
    )
)

Both are injected as standard environment variables. The CLI flags take KEY=VALUE and can repeat.

Environment variables are stored in plain text and visible when you inspect the sandbox.
Secrets are encrypted at rest, never returned in API responses, and obfuscated in CLI output. Use them for API keys, passwords, and anything you wouldn’t want in logs.

For a single command, pass env vars on the command instead: see Run a command.

Inject secrets into request headers

Give a sandbox a credential that it can use without ever being able to see it. Store the credential once as a secret. Then add a header rule for a host to the sandbox’s network policy. The platform adds the secret to HTTPS request headers for that host, outside the sandbox. The value never goes into the sandbox’s environment, files, or configuration.

# 1. Store the credential once
prime secret create --name INFERENCE_KEY --value "your-api-key"

# 2. Create a sandbox with a header rule for Prime Inference
prime sandbox create python:3.11-slim \
  --name api-agent \
  --network-allow api.pinference.ai \
  --inject-header api.pinference.ai 'Authorization: Bearer ${prime.secrets.INFERENCE_KEY}'

# 3. Inside the sandbox, call the API without a key
#    curl https://api.pinference.ai/api/v1/models

from prime_sandboxes import (
    APIClient, SandboxClient, CreateSandboxRequest, HeaderRule, Secret
)

# 1. Store the credential once:
#    prime secret create --name INFERENCE_KEY --value "your-api-key"

# 2. Create a sandbox with a header rule for Prime Inference
client = SandboxClient(APIClient())
sandbox = client.create(
    CreateSandboxRequest(
        name="api-agent",
        docker_image="python:3.11-slim",
        network_allowlist=["api.pinference.ai"],
        network_rules={
            "api.pinference.ai": HeaderRule(
                headers={"Authorization": f"Bearer {Secret.fill('INFERENCE_KEY')}"}
            )
        },
    )
)

The rule refers to the secret by name: ${prime.secrets.INFERENCE_KEY}. When the sandbox sends an HTTPS request to api.pinference.ai, the platform resolves the reference outside the sandbox, sets the header, and sends the request on. If the sandbox sends a header with the same name, the platform replaces it.

The destination host receives the header, so it can read the credential. A response can also send the value back into the sandbox. Add header rules only for hosts that you trust.

A header rule does not give network access. The sandbox’s allowlist or denylist must also allow the rule host.

Which secrets you can use

Header rules use your global secrets: the secrets that you create with prime secret create or under Keys & Secrets. These are the same secrets that you can link to Environments Hub environments, so one secret can serve both. Secrets set directly on one environment are not available to header rules. The secret must belong to the same user or team as the sandbox.

Rule syntax and limits

Item	Limit
Reference syntax	`${prime.secrets.<NAME>}`. The name uses the secret name rules.
Rule hosts per sandbox	32
Header size per rule host (names and values)	8 KiB
Different secrets per rule host	10
Secret value size	16 KiB
Header size per request, after the platform adds the secrets	32 KiB
Protocol	HTTPS on port 443 only. Plain HTTP is not changed.
Secret updates	An updated secret (`prime secret update`) applies in 60 seconds or less. You do not need to restart the sandbox.

A rule host is an exact host name (api.pinference.ai) or a wildcard for one label (*.example.com). *.example.com matches api.example.com, but not example.com or a.b.example.com. Ports, paths, and IP addresses are not permitted.
Host names are not case-sensitive. An exact host has priority over a wildcard. The platform does not combine rules.
A header value is text that contains zero or more ${prime.secrets.<NAME>} references. Other ${...} forms are not permitted.
Header names are not case-sensitive. A rule cannot set the same header two times, for example Authorization and authorization.
You cannot set these headers: Host, :authority, Content-Length, Transfer-Encoding, Connection, Upgrade, Keep-Alive, TE, Trailer, and headers that start with Proxy-.

Update rules on a running sandbox

Header rules are part of the network policy. Each update replaces the full policy, as for allowlists and denylists.

# Replace the policy. Include the allow or deny list with the rules.
prime sandbox network sbx_123 \
  --allow 'api.pinference.ai,*.example.com' \
  --inject-header api.pinference.ai 'Authorization: Bearer ${prime.secrets.INFERENCE_KEY}'

# Set more than one header for a host: use --inject-header one time for each header
prime sandbox network sbx_123 --allow '*' \
  --inject-header api.pinference.ai 'Authorization: Bearer ${prime.secrets.INFERENCE_KEY}' \
  --inject-header api.pinference.ai 'X-Prime-Team-ID: your-team-id'

# Show the current rules
prime sandbox network sbx_123

client.set_network(
    sandbox.id,
    allow=["api.pinference.ai", "*.example.com"],
    rules={
        "api.pinference.ai": HeaderRule(
            headers={"Authorization": f"Bearer {Secret.fill('INFERENCE_KEY')}"}
        )
    },
)

For many rules, put the policy in a JSON file and use --network-policy. You can use it when you create or update a sandbox:

{
  "allow": ["api.pinference.ai", "api.primeintellect.ai"],
  "rules": {
    "api.pinference.ai": {
      "headers": { "Authorization": "Bearer ${prime.secrets.INFERENCE_KEY}" }
    },
    "api.primeintellect.ai": {
      "headers": { "Authorization": "Bearer ${prime.secrets.PLATFORM_KEY}" }
    }
  }
}

If you replace the policy without rules, the platform removes all header rules.

Errors

If the platform cannot add a secret, it does not send the request. The sandbox gets a 502 response with the body request blocked: header substitution unavailable. A partial credential never goes to the destination.

Situation	Result
The secret is deleted	Requests to the rule host continue for up to 60 seconds, then fail with the `502`
A rule is removed while the sandbox runs	Requests on open connections to that host fail with the `502`. New connections follow the normal network policy without headers.

Requests to hosts without a rule are not affected.

TLS trust inside the sandbox

To add headers, the platform must terminate TLS for rule hosts. Clients in the sandbox must therefore trust the Prime Intellect root certificate. The sandbox includes this certificate at /mnt/sandboxd/platform-ca.pem.

Most clients work with no changes. At boot, the platform adds the root to the sandbox’s system trust store. It also sets SSL_CERT_FILE, REQUESTS_CA_BUNDLE, and NODE_EXTRA_CA_CERTS, unless you set them. This covers curl, openssl, Python requests and urllib, and Node.js.
If the image does not include the ca-certificates package, install it in the image. You can also install it while the sandbox runs.
If a client uses its own trust store, add the root to that store, as in the example below.

import ssl, urllib.request, certifi

context = ssl.create_default_context(cafile=certifi.where())
context.load_verify_locations("/mnt/sandboxd/platform-ca.pem")

with urllib.request.urlopen("https://api.pinference.ai/api/v1/models", context=context) as response:
    body = response.read()

Add the root to the existing certificates. Do not replace them. Do not turn off certificate verification. Connections to hosts without a rule keep end-to-end TLS, so they do not need the root.

Known limits

Clients that use certificate pinning cannot connect to rule hosts.
Clients that use Encrypted Client Hello (ECH) cannot connect to rule hosts. Browsers that send GREASE ECH, such as Chromium, work normally.

Getting Started

Inference

Model Factory

Community

Compute

Traces

Libraries

Inject secrets into request headers

Which secrets you can use

Rule syntax and limits

Update rules on a running sandbox

Errors

TLS trust inside the sandbox

Known limits

​Inject secrets into request headers

​Which secrets you can use

​Rule syntax and limits

​Update rules on a running sandbox

​Errors

​TLS trust inside the sandbox

​Known limits

Inject secrets into request headers

Which secrets you can use

Rule syntax and limits

Update rules on a running sandbox

Errors

TLS trust inside the sandbox

Known limits