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: { 'X-Header': 'Content' },
          },
        },
      ],
    },
  },
})

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": {"X-Header": "Content"},
                    },
                },
            ],
        },
    },
)

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]

🦋 Changeset detected

Latest commit: 708c7b5

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 2 packages

Name	Type
e2b	Minor
@e2b/python-sdk	Minor

Not sure what this means? Click here to learn what changesets are.

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

[cursor]

PR Summary

Medium Risk
Introduces new network configuration shapes (selectors, per-host transform rules, and a new PUT /sandboxes/{sandboxID}/network endpoint) across generated clients, which risks breaking consumers relying on previous network types/serialization. Also adds request header injection support and placeholder-based transforms, which are sensitive to backend/proxy behavior and contract mismatches.

Overview
Adds structured egress network.rules keyed by host to apply per-host request transforms (currently header injection), including support for transform callbacks that emit placeholder strings for the proxy to resolve at egress time.

Extends network.allowOut/denyOut (JS) and allow_out/deny_out (Python) to accept selector callbacks that can reference an allTraffic sentinel and the set of rule-registered hosts, and updates SDK request building to materialize these into the API wire format.

Updates the OpenAPI spec and regenerated JS/Python clients to include the new network rule/transform schemas, adds PUT /sandboxes/{sandboxID}/network for updating a running sandbox’s network config, and expands metrics (memCache) and node status (standby). Tests are updated/added to cover selector usage and header-injection transform behavior.

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

[github-actions]

Package Artifacts

Built from 9d859c9. Download artifacts from this workflow run.

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

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

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

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

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

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

[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.}

[claude]

⚠️ Code review skipped — your organization has reached its monthly code review spending cap.

An organization admin can view or raise the cap at claude.ai/admin-settings/claude-code. The cap resets at the start of the next billing period.

Once the cap resets or is raised, reopen this pull request to trigger a review.

[cursor]

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

There are 2 total unresolved issues (including 1 from previous review).

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

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

[nauxliu]

Thanks for working on this. I’m trying to understand the intended pattern for credential brokering and request logging.

For our use case, we want connectors to integrate with third-party platforms like CRMs, Jira, GitHub, etc. Sandboxes need to make outbound API calls to these services, while the actual credentials should stay outside the sandbox. The credential to inject may depend on the actual sandbox, tenant, and user.

Ideally, this would be an egress-time callback where we can access the original outbound request, inspect the URL / method / headers, inject the right token, and log or audit the request.

From my reading, transform is evaluated at sandbox creation time and produces a static config. It does not run at egress time, cannot do async lookup, cannot access the original request, and cannot use the real runtime sandbox context. That makes dynamic credential injection and request logging difficult.

If the design is intentionally static, could E2B at least support updating the network config after sandbox creation, similar to Vercel’s updateNetworkPolicy()? That would allow us to create the sandbox, resolve credentials based on the real sandbox ID, and then patch the transform.

Is that the expected workaround, or is there a better recommended pattern?

[mishushakov]

@nauxliu thanks for the feedback!

We will consider making it possible to update the networking configuration after the Sandbox creation - I will check in with the team!