Outbound request header transformation

How it works

When an egress request from the sandbox passes through the node egress proxy, the platform matches network.rules against the target domain and adds or overrides headers, or replaces placeholders in header values, for matched requests.

For HTTP requests, the platform modifies headers directly at the node egress proxy. For HTTPS requests, the platform must decrypt the traffic first, so it performs TLS inspection at the node egress proxy: it dynamically issues a certificate for the target domain using the platform CA and validates the HTTPS certificate presented by the real upstream service. Sandbox clients must trust the platform CA; otherwise HTTPS requests return certificate errors. For template requirements, see Prerequisites.

Prerequisites

• Prepare real credentials in the control-plane execution environment. The examples in this topic read credentials from the API_TOKEN environment variable; real credentials never enter the sandbox.

• If code inside the sandbox accesses target domains over HTTPS, the template must include the platform CA:

  • Official templates and supported Debian/Ubuntu custom templates have the platform CA built in, and curl, Python requests, and Node.js work out of the box.

  • Official images must be at least version v0.0.44:

    • fc-e2b-registry.${regionId}.cr.aliyuncs.com/runtime/base:v0.0.44

    • fc-e2b-registry.${regionId}.cr.aliyuncs.com/runtime/code-interpreter-v1:v0.0.44

  • Custom images must be built after the platform release of 2026-08-15. Earlier images do not receive the platform CA automatically.

Choose a transformation method

When the same header matches both methods, the platform performs placeholder replacement first and then full header injection; the injected value takes final precedence.

Full header injection

import { Sandbox } from "e2b";

const token = process.env.API_TOKEN;
if (!token) throw new Error("API_TOKEN is required");

const sandbox = await Sandbox.create({
  network: {
    allowOut: ["api.example.com"],
    denyOut: ["0.0.0.0/0"],
    rules: {
      "api.example.com": [
        {
          transform: {
            headers: {
              Authorization: `Bearer ${token}`,
            },
          },
        },
      ],
    },
  },
});
console.log(`[create] Sandbox created: ${sandbox.sandboxId}`);

// When code inside the sandbox calls https://api.example.com,
// the platform injects the Authorization header automatically;
// the business code does not need to set this header.

import os

from e2b import Sandbox

token = os.environ["API_TOKEN"]

sandbox = Sandbox.create(
    network={
        "allow_out": ["api.example.com"],
        "deny_out": ["0.0.0.0/0"],
        "rules": {
            "api.example.com": [
                {
                    "transform": {
                        "headers": {"Authorization": f"Bearer {token}"}
                    }
                }
            ]
        },
    },
)
print(f"[create] Sandbox created: {sandbox.sandbox_id}")

Code inside the sandbox calls https://api.example.com as usual without setting Authorization. The target service receives the header injected by the platform.

Header value placeholder replacement

The current E2B SDK does not expose a standalone replacement field. FC Agent Sandbox carries replacement rules in a reserved header key whose value must be a JSON string containing a replacement array:

fc.sandbox.network.header-value-replacements

This key is used only when creating or updating rules. It is never sent to the target service as a real HTTP header.

import { Sandbox } from "e2b";

const token = process.env.API_TOKEN;
if (!token) throw new Error("API_TOKEN is required");

const replacements = JSON.stringify([
  { placeholder: "TOKEN_PLACEHOLDER", value: token },
]);

const sandbox = await Sandbox.create({
  network: {
    allowOut: ["api.example.com"],
    denyOut: ["0.0.0.0/0"],
    rules: {
      "api.example.com": [
        {
          transform: {
            headers: {
              "fc.sandbox.network.header-value-replacements": replacements,
            },
          },
        },
      ],
    },
  },
});

import json
import os

from e2b import Sandbox

token = os.environ["API_TOKEN"]
carrier = json.dumps(
    [{"placeholder": "TOKEN_PLACEHOLDER", "value": token}]
)

sandbox = Sandbox.create(
    network={
        "allow_out": ["api.example.com"],
        "deny_out": ["0.0.0.0/0"],
        "rules": {
            "api.example.com": [
                {
                    "transform": {
                        "headers": {
                            "fc.sandbox.network.header-value-replacements": carrier
                        }
                    }
                }
            ]
        },
    },
)

After the configuration is in place, when sandbox code or a third-party SDK sends:

Authorization: Bearer TOKEN_PLACEHOLDER

The target service receives:

Authorization: Bearer real token

Replacement is case-sensitive, and all occurrences within the same header value are replaced. The scan runs only once—the generated output does not trigger another round of replacement—and unmatched placeholders are sent to the target service as-is.

Update rules at runtime

network.rules can be modified without rebuilding the sandbox: call updateNetwork in Node.js, or update_network in Python. PUT /sandboxes/{id}/network is a full replacement, not an incremental update: every update must submit the complete allowOut, denyOut, and rules. Omitting rules, or passing null or {}, clears the existing rules.

If an update fails, the previous rules remain in effect. Network rules are preserved while the sandbox is paused, and network.rules can also be updated while paused; after the sandbox resumes, the latest rules apply.

import { Sandbox } from "e2b";

const sandbox = await Sandbox.create({
  network: {
    allowOut: ["api.example.com"],
    denyOut: ["0.0.0.0/0"],
  },
});
console.log(`[create] Sandbox created: ${sandbox.sandboxId}`);

// Add rules later
await sandbox.updateNetwork({
  allowOut: ["api.example.com"],
  denyOut: ["0.0.0.0/0"],
  rules: {
    "api.example.com": [
      {
        transform: {
          headers: {
            Authorization: `Bearer ${process.env.API_TOKEN}`,
          },
        },
      },
    ],
  },
});
console.log("[update] network.rules applied");

// Clear rules
await sandbox.updateNetwork({
  allowOut: ["api.example.com"],
  denyOut: ["0.0.0.0/0"],
});
console.log("[update] network.rules cleared");

import os

from e2b import Sandbox

sandbox = Sandbox.create(
    network={
        "allow_out": ["api.example.com"],
        "deny_out": ["0.0.0.0/0"],
    },
)
print(f"[create] Sandbox created: {sandbox.sandbox_id}")

# Add rules later
sandbox.update_network({
    "allow_out": ["api.example.com"],
    "deny_out": ["0.0.0.0/0"],
    "rules": {
        "api.example.com": [
            {
                "transform": {
                    "headers": {
                        "Authorization": f"Bearer {os.environ['API_TOKEN']}"
                    }
                }
            }
        ]
    },
})
print("[update] network.rules applied")

# Clear rules
sandbox.update_network({
    "allow_out": ["api.example.com"],
    "deny_out": ["0.0.0.0/0"],
})
print("[update] network.rules cleared")

The network.rules returned by getInfo or GET /sandboxes/{id} reflects the currently effective rules. Use it to verify current rule content or as input for subsequent updates. In the response, each replacement rule is re-encoded as a JSON string carried by the reserved header key, and the real value is returned in plaintext. Do not write the response into general logs, tickets, or frontend error reporting.

Security recommendations

• Read and submit real credentials only from a trusted control plane. Never commit secrets to code repositories.

• Use a secrets management service, CI secrets, or short-lived, authenticated business credentials.

• Prefer HTTPS. Once an HTTP request leaves the node egress proxy, it is plaintext, and credentials may leak in transit.

• Use short-lived, least-privilege credentials that can be revoked per tenant or per session.

• Configure exact domains only for real targets, and confirm that the target does not echo or log authentication headers.

• Protect the identity permissions of the create, update, and query APIs, and avoid printing the complete network.rules.

• Never put a real, usable credential into a placeholder itself.

Limits

In network.rules, each exact domain maps to one rule object, and the rule object carries ordinary headers or replacement rules through transform.headers. The following limits apply:

A placeholder must not be the same as the real value, must not be duplicated, and must not be a substring of another placeholder.

The following header categories cannot be configured or are skipped during replacement: Host, Content-Length, Transfer-Encoding, Connection, Upgrade, proxy authentication headers, x-envoy-*, x-forwarded-*, and other routing or frame control headers. The restricted set may change across platform versions; do not rely on the behavior of these headers on a specific version.

FAQ