feat(sdk): support structured network rules with per-host transforms

[mishushakov]

Summary

• Adds a network.rules map keyed by host (or CIDR / IP) for per-host outbound request transforms (e.g. header injection). Registering a host in rules does not grant egress on its own — it must still be referenced via allowOut. JS accepts either a plain object or a Map.
• Extends network.allowOut / network.denyOut to accept either a static list or a selector callback receiving { allTraffic, rules } (Python: ctx.all_traffic, ctx.rules). allTraffic is '0.0.0.0/0'; rules is a Map (Python Mapping) view of network.rules, so policies can be composed against the registered rule hosts without duplicating them.
• transform on a rule accepts either a static object or a callback that receives a typed SandboxNetworkTransformContext. The context fields are literal placeholder strings (${e2b.sandboxId}, ${e2b.teamId}, ${e2b.executionId}, ${e2b.identity.jwt}) that the egress proxy resolves per request — so users get typed access without hardcoding template strings.
• Updates the OpenAPI spec, regenerates JS and Python API clients, and surfaces new types: SandboxNetworkRule, SandboxNetworkRules, SandboxNetworkTransform, SandboxNetworkTransformContext, SandboxNetworkSelector, SandboxNetworkSelectorContext, SandboxNetworkInfo.
• Adds contract tests (JS + async/sync Python) that create a sandbox with a transform.headers rule for httpbin.org, run curl https://httpbin.org/headers, and assert the injected header is reflected back.

Examples

Inject a static header on requests to a specific host (TypeScript)

import { Sandbox } from 'e2b'

await Sandbox.create({
  network: {
    // Only allow egress to hosts that have rules registered.
    allowOut: ({ rules }) => [...rules.keys()],
    rules: {
      'api.openai.com': [
        {
          transform: {
            headers: { Authorization: `Bearer ${process.env.OPENAI_API_KEY}` },
          },
        },
      ],
    },
  },
})

Same thing in Python

import os
from e2b import Sandbox

sandbox = Sandbox(
    network={
        "allow_out": lambda ctx: list(ctx.rules.keys()),
        "rules": {
            "api.openai.com": [
                {
                    "transform": {
                        "headers": {"Authorization": f"Bearer {os.environ['OPENAI_API_KEY']}"},
                    },
                },
            ],
        },
    },
)

Transform callback — inject the sandbox's identity JWT (resolved per request)

The proxy substitutes ${e2b.identity.jwt} (and the other placeholder fields) at egress time, so the same template is reused across all requests without ever materializing the secret in your code:

await Sandbox.create({
  network: {
    allowOut: ({ rules }) => [...rules.keys()],
    rules: {
      'api.internal.example.com': [
        {
          transform: ({ identity, sandboxId }) => ({
            headers: {
              Authorization: `Bearer ${identity.jwt}`,
              'X-Sandbox-Id': sandboxId,
            },
          }),
        },
      ],
    },
  },
})

Sandbox(
    network={
        "allow_out": lambda ctx: list(ctx.rules.keys()),
        "rules": {
            "api.internal.example.com": [
                {
                    "transform": lambda ctx: {
                        "headers": {
                            "Authorization": f"Bearer {ctx.identity.jwt}",
                            "X-Sandbox-Id": ctx.sandbox_id,
                        },
                    },
                },
            ],
        },
    },
)

network.rules as a Map (TypeScript)

const rules = new Map([
  ['api.openai.com', [{ transform: { headers: { 'X-Trace': 'on' } } }]],
])

await Sandbox.create({
  network: { allowOut: ({ rules }) => [...rules.keys()], rules },
})

Block all egress except an explicit allowlist

await Sandbox.create({
  network: {
    denyOut: ({ allTraffic }) => [allTraffic],   // allTraffic === '0.0.0.0/0'
    allowOut: ['1.1.1.1', '8.8.8.0/24'],
  },
})

Sandbox(
    network={
        "deny_out": lambda ctx: [ctx.all_traffic],
        "allow_out": ["1.1.1.1", "8.8.8.0/24"],
    },
)

Static list (unchanged, still supported)

await Sandbox.create({
  network: { allowOut: ['1.1.1.1', '8.8.8.0/24'] },
})

Sandbox(network={"allow_out": ["1.1.1.1", "8.8.8.0/24"]})

Notes

• SDK/spec-only; the sandbox egress proxy still needs to honor transform.headers and resolve the placeholder strings for the httpbin assertion to pass end-to-end — the new test locks the wire shape as a contract.
• ALL_TRAFFIC is still exported but the selector form (({ allTraffic }) => [allTraffic] / lambda ctx: [ctx.all_traffic]) is the recommended way to express "everything".
• Transform callbacks are evaluated client-side at sandbox creation; the resolved object (containing the literal ${e2b.*} placeholders) is sent on the wire. The proxy substitutes the placeholders per request — they are not resolved by the SDK.

Test plan

• Spec + generated clients reviewed for shape correctness
• Existing network.test.ts / test_network.py cases still pass once backend auth is available
• New firewall transform injects headers cases pass once egress proxy injects headers
• Egress proxy resolves ${e2b.sandboxId}, ${e2b.teamId}, ${e2b.executionId}, ${e2b.identity.jwt} placeholders in transform.headers values

[changeset-bot]

⚠️ No Changeset found

Latest commit: 0653579

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[cursor]

PR Summary

Medium Risk
Extends SDK/network configuration types and request-body building logic, which can change the wire format sent to the API and affect sandbox egress behavior. Risk is moderate because changes span OpenAPI spec, generated clients, and both JS/Python SDK surfaces, but remain SDK/spec-scoped.

Overview
Adds support for structured sandbox egress configuration via network.rules (per-host rule lists with optional request transform such as header injection) and expands allowOut/denyOut to accept either a static list or a selector callback receiving { allTraffic, rules }.

Updates the OpenAPI spec and regenerated JS/Python clients accordingly, including a new PUT /sandboxes/{sandboxID}/network endpoint and new schema/types (SandboxNetworkRule, SandboxNetworkTransform, SandboxNetworkInfo), plus adds contract tests (JS + sync/async Python) validating header injection behavior against httpbin.org. Also extends node/metrics schema with NodeStatus: standby and a new sandbox metric field memCache.

^{Reviewed by Cursor Bugbot for commit 0653579. Bugbot is set up for automated code reviews on this repo. Configure here.}

[github-actions]

Package Artifacts

Built from 17ec9fb. Download artifacts from this workflow run.

JS SDK (e2b@2.19.3-mishushakov-network-allowout-transform.0):

npm install ./e2b-2.19.3-mishushakov-network-allowout-transform.0.tgz

CLI (@e2b/cli@2.10.1-mishushakov-network-allowout-transform.0):

npm install ./e2b-cli-2.10.1-mishushakov-network-allowout-transform.0.tgz

Python SDK (e2b==2.20.2+mishushakov-network-allowout-transform):

pip install ./e2b-2.20.2+mishushakov.network.allowout.transform-py3-none-any.whl

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit f8ea7fa. Configure here.}

[cursor]

JS SDK SandboxMetrics missing new memCache field

Medium Severity

The OpenAPI spec adds memCache as a required field on SandboxMetric (visible in the spec diff and in the generated schema.gen.ts at line 2321), and the Python generated client (sandbox_metric.py) was updated accordingly. However, the JS SDK's hand-written SandboxMetrics interface does not include memCache. Any metrics mapping code will silently drop this field, making it inaccessible to JS SDK consumers.

 

^{Reviewed by Cursor Bugbot for commit f8ea7fa. Configure here.}