Proxy

Route outbound sandbox traffic through Blaxel’s proxy with MITM header and body injection, inject secrets, and configure per-domain firewalls.

This feature is currently in public preview and is not recommended for production use.

The Blaxel SDK supports two network features when creating sandboxes:

• Proxy routing with secrets injection - the Blaxel proxy performs man-in-the-middle (MITM) interception on outbound HTTPS traffic and injects headers, body fields, and secrets server-side.
• Domain filtering - the Blaxel proxy controls which external domains the sandbox can reach.

Proxy and network configuration can be updated after creation: you can rotate secrets, add or remove routing rules, and change the domain allowlist or denylist on a running sandbox.

You cannot enable the proxy on a sandbox that was created without it, or fully disable the proxy on a sandbox that was created with it. Enabling or disabling the proxy requires a new sandbox. If you remove all routing rules and domain filters from an existing proxy-enabled sandbox, the proxy remains active transparently — traffic continues to flow through it without any secret injection or domain blocking.

How it works

When a sandbox is created with a proxy config, Blaxel:

1. Sets HTTP_PROXY, HTTPS_PROXY, and NO_PROXY environment variables inside the sandbox
2. Installs a CA certificate and sets NODE_EXTRA_CA_CERTS and SSL_CERT_FILE so TLS clients trust the proxy
3. Performs MITM on outbound HTTPS via CONNECT tunneling
4. Matches each request against routing rules by destination domain
5. Injects configured headers and body fields, resolving {{SECRET:name}} placeholders server-side
6. Adds an X-Blaxel-Request-Id header to every proxied request for tracing

Most HTTP clients work transparently because they read the injected HTTP_PROXY, HTTPS_PROXY, and SSL_CERT_FILE environment variables — curl, pip, npm, git, Python requests, and Python httpx all work out of the box. Lower-level libraries that don’t follow these conventions (for example, calling urllib3 directly) need to be pointed at the proxy explicitly.

Localhost (127.0.0.1), private ranges (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16), 169.254.169.254, .local, and .internal are always bypassed automatically.

Configuration reference

All network settings are passed via the network key in the sandbox creation options:

TypeScript

import { SandboxInstance } from "@blaxel/core";

const sandbox = await SandboxInstance.create({
  name: "my-sandbox",
  image: "blaxel/base-image:latest",
  region: "us-was-1",
  network: {
    // Domain filtering (firewall)
    allowedDomains: [...],
    forbiddenDomains: [...],
    // Proxy with header/body injection
    proxy: {
      routing: [...],
      bypass: [...],
    },
  },
});

from blaxel.core.sandbox import SandboxInstance

sandbox = await SandboxInstance.create({
    "name": "my-sandbox",
    "image": "blaxel/base-image:latest",
    "region": "us-was-1",
    "network": {
        # Domain filtering (firewall)
        "allowedDomains": [...],
        "forbiddenDomains": [...],
        # Proxy with header/body injection
        "proxy": {
            "routing": [...],
            "bypass": [...],
        },
    },
})

SandboxNetwork

Field	Type	Description
allowedDomains	string[] / list[str]	Allowlist — only these domains are reachable. Supports wildcards (*.s3.amazonaws.com).
forbiddenDomains	string[] / list[str]	Denylist — all domains except these are reachable. Supports wildcards. If both are set, allowedDomains takes precedence.
proxy	ProxyConfig	Proxy routing and bypass configuration.

ProxyConfig

Field	Type	Description
routing	ProxyTarget[] / list[ProxyTarget]	Per-destination routing rules with header/body injection.
bypass	string[] / list[str]	Domains added to NO_PROXY that skip the proxy entirely. Supports wildcards.

ProxyTarget

Field	Type	Description
destinations	string[] / list[str]	Domain patterns this rule applies to. Use ["*"] for a global catch-all rule. Supports wildcards (*.example.com matches sub.example.com but not example.com).
headers	Record<string, string> / dict	Headers injected into matching requests. Values may contain {{SECRET:name}} references.
body	Record<string, string> / dict	JSON body fields injected into matching requests. Values may contain {{SECRET:name}} references.
secrets	Record<string, string> / dict	Named secret values for this rule. Referenced via {{SECRET:name}} in headers and body. Write-only — never returned in API responses. Stored encrypted at rest.

Region availability

Proxy availability is region-dependent. The Region type includes a proxyAvailable boolean field. Check region support before relying on proxy features:

TypeScript

import { listRegions } from "@blaxel/core";

const { data: regions } = await listRegions({ throwOnError: true });
for (const r of regions) {
  console.log(`${r.name}: proxy=${r.proxyAvailable}`);
}

from blaxel.core import listRegions

result = await listRegions()
for r in result.data:
    print(f"{r.name}: proxy={r.proxy_available}")

Environment variables set inside the sandbox

When proxy is configured, the sandbox automatically has:

Variable	Purpose
HTTP_PROXY	Proxy URL for HTTP traffic
HTTPS_PROXY	Proxy URL for HTTPS traffic
NO_PROXY	Comma-separated bypass list (always includes localhost, private ranges)
NODE_EXTRA_CA_CERTS	Path to CA cert for Node.js TLS verification
SSL_CERT_FILE	Path to CA cert for other TLS clients (curl, Python, etc.)

CLI tool compatibility

When proxy is enabled, common CLI tools and high-level clients work transparently inside the sandbox with no extra configuration:

Tool	Protocol	Notes
curl	HTTPS	Automatic via HTTPS_PROXY env var
git	HTTPS	May need GIT_SSL_CAINFO=$SSL_CERT_FILE for some operations
pip / pip3	HTTPS	Automatic
npm / npx	HTTPS	Automatic
Python requests	HTTPS	Automatic via env vars
Python httpx	HTTPS	Automatic via env vars

Python’s stdlib urllib.request is not recommended with the proxy. Prefer requests or httpx, or configure urllib3.ProxyManager directly if you need lower-level control:

import os
import urllib.parse
import urllib3

proxy_url = os.environ["HTTPS_PROXY"]
_parsed = urllib.parse.urlsplit(proxy_url)
_userinfo = _parsed.netloc.rsplit("@", 1)
proxy_kwargs = {}
if len(_userinfo) == 2:
    proxy_auth = urllib.parse.unquote(_userinfo[0])
    proxy_kwargs["proxy_headers"] = urllib3.make_headers(proxy_basic_auth=proxy_auth)
http = urllib3.ProxyManager(
    proxy_url,
    **proxy_kwargs,
    cert_reqs="CERT_REQUIRED",
    ca_certs=os.environ.get("SSL_CERT_FILE"),
)
resp = http.request(
    "GET",
    "https://api.stripe.com/v1/charges"
)
print(resp.status, resp.data.decode())

Behavior details

• Wildcard matching: *.example.com matches sub.example.com and a.b.example.com but not example.com itself
• No cross-route leakage: Headers/secrets from one routing rule are never applied to requests matching a different rule
• User headers preserved: The proxy adds injected headers alongside any headers the sandbox code sends — it does not overwrite user-sent headers
• Body merge: Injected body fields are merged into JSON request bodies up to 1 MB. User-sent fields take precedence on key collisions. Requests over 1 MB, requests without a known Content-Length (e.g. chunked uploads), and streaming RPCs are forwarded unchanged — use header injection for credentials in those cases
• Tracing: Every proxied request gets an X-Blaxel-Request-Id header for observability
• Local traffic: Requests to localhost / 127.0.0.1 are never routed through the proxy

HTTP/2 and gRPC

The proxy supports HTTP/2 and gRPC. Clients that previously required HTTP/1.1 workarounds now work without any flags or downgrades:

• gRPC SDKs in Go, Python (grpcio), and Node (@grpc/grpc-js)
• curl --http2
• Go net/http (HTTP/2 is the default)

All four gRPC RPC styles — unary, server-streaming, client-streaming, and bidirectional — flow through, and gRPC trailers (grpc-status, grpc-message) are preserved end-to-end.

A few things to keep in mind:

• Header injection works on every request, including streaming RPCs.
• Body injection is skipped on streaming requests (gRPC streams, chunked uploads). Use header injection to attach credentials on streaming workloads — see the body injection limits in Behavior details.

Update proxy configuration

You can update proxy routing rules, secrets, domain filters, and bypass lists on a running sandbox using the SDK’s updateNetwork method. This fetches the current sandbox, merges the new network config, and applies the update in one call:

TypeScript

import { SandboxInstance } from "@blaxel/core";

await SandboxInstance.updateNetwork("my-sandbox", {
  network: {
    allowedDomains: ["api.stripe.com", "api.openai.com", "api.anthropic.com"],
    proxy: {
      routing: [
        {
          destinations: ["api.stripe.com"],
          headers: { "Authorization": "Bearer {{SECRET:stripe-key}}" },
          secrets: { "stripe-key": "sk_live_REPLACE_WITH_YOUR_KEY" },
        },
        {
          destinations: ["api.anthropic.com"],
          headers: { "x-api-key": "{{SECRET:anthropic-key}}" },
          secrets: { "anthropic-key": "REPLACE_WITH_YOUR_ANTHROPIC_KEY" },
        },
      ],
    },
  },
});

from blaxel.core.sandbox import SandboxInstance
from blaxel.core.sandbox.types import SandboxUpdateNetwork

await SandboxInstance.update_network(
    "my-sandbox",
    SandboxUpdateNetwork(network={
        "allowedDomains": ["api.stripe.com", "api.openai.com", "api.anthropic.com"],
        "proxy": {
            "routing": [
                {
                    "destinations": ["api.stripe.com"],
                    "headers": {"Authorization": "Bearer {{SECRET:stripe-key}}"},
                    "secrets": {"stripe-key": "sk_live_REPLACE_WITH_YOUR_KEY"},
                },
                {
                    "destinations": ["api.anthropic.com"],
                    "headers": {"x-api-key": "{{SECRET:anthropic-key}}"},
                    "secrets": {"anthropic-key": "REPLACE_WITH_YOUR_ANTHROPIC_KEY"},
                },
            ],
        },
    }),
)

curl -X PUT "https://api.blaxel.ai/v0/sandboxes/my-sandbox" \
  -H "Authorization: Bearer $BL_API_KEY" \
  -H "X-Blaxel-Workspace: my-workspace" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": { "name": "my-sandbox" },
    "spec": {
      "network": {
        "allowedDomains": ["api.stripe.com", "api.openai.com", "api.anthropic.com"],
        "proxy": {
          "routing": [
            {
              "destinations": ["api.stripe.com"],
              "headers": { "Authorization": "Bearer {{SECRET:stripe-key}}" },
              "secrets": { "stripe-key": "sk_live_REPLACE_WITH_YOUR_KEY" }
            },
            {
              "destinations": ["api.anthropic.com"],
              "headers": { "x-api-key": "{{SECRET:anthropic-key}}" },
              "secrets": { "anthropic-key": "REPLACE_WITH_YOUR_ANTHROPIC_KEY" }
            }
          ]
        }
      }
    }
  }'

The update replaces the entire network configuration. Include all routing rules, domain filters, and secrets you want active after the update.

You cannot enable the proxy on a sandbox that was created without it, or fully disable the proxy on a sandbox that was created with it. Removing all routing rules and domain filters does not disable the proxy — traffic continues to flow through it transparently without any injection or blocking.

Full example: agent sandbox with proxy + firewall

TypeScript

import { SandboxInstance } from "@blaxel/core";

const sandbox = await SandboxInstance.create({
  name: "agent-workspace",
  image: "blaxel/base-image:latest",
  region: "us-was-1",
  labels: { team: "ml", env: "staging" },
  network: {
    allowedDomains: [
      "api.stripe.com",
      "api.openai.com",
      "httpbin.org",
      "*.s3.amazonaws.com",
    ],
    proxy: {
      routing: [
        {
          destinations: ["api.stripe.com"],
          headers: {
            "Authorization": "Bearer {{SECRET:stripe-key}}",
            "Stripe-Version": "2024-12-18.acacia",
          },
          body: {
            "api_key": "{{SECRET:stripe-key}}",
          },
          secrets: {
            "stripe-key": "sk-live-abc123...",
          },
        },
        {
          destinations: ["api.openai.com"],
          headers: {
            "Authorization": "Bearer {{SECRET:openai-key}}",
            "OpenAI-Organization": "org-abc123",
          },
          secrets: {
            "openai-key": "sk-proj-xyz789...",
          },
        },
      ],
      bypass: ["*.s3.amazonaws.com"],
    },
  },
});

// curl https://api.stripe.com/...  -> gets auth header + body injected
// curl https://api.openai.com/...  -> gets auth header injected
// curl https://httpbin.org/...     -> allowed, no injection
// curl https://evil.com/...        -> BLOCKED by allowedDomains firewall

const result = await sandbox.process.exec({
  command: "curl -s https://api.stripe.com/v1/charges",
  waitForCompletion: true,
});
console.log(result.logs);

from blaxel.core.sandbox import SandboxInstance

sandbox = await SandboxInstance.create({
    "name": "agent-workspace",
    "image": "blaxel/base-image:latest",
    "region": "us-was-1",
    "labels": {"team": "ml", "env": "staging"},
    "network": {
        "allowedDomains": [
            "api.stripe.com",
            "api.openai.com",
            "httpbin.org",
            "*.s3.amazonaws.com",
        ],
        "proxy": {
            "routing": [
                {
                    "destinations": ["api.stripe.com"],
                    "headers": {
                        "Authorization": "Bearer {{SECRET:stripe-key}}",
                        "Stripe-Version": "2024-12-18.acacia",
                    },
                    "body": {
                        "api_key": "{{SECRET:stripe-key}}",
                    },
                    "secrets": {
                        "stripe-key": "sk-live-abc123...",
                    },
                },
                {
                    "destinations": ["api.openai.com"],
                    "headers": {
                        "Authorization": "Bearer {{SECRET:openai-key}}",
                        "OpenAI-Organization": "org-abc123",
                    },
                    "secrets": {
                        "openai-key": "sk-proj-xyz789...",
                    },
                },
            ],
            "bypass": ["*.s3.amazonaws.com"],
        },
    },
})

# curl https://api.stripe.com/...  -> gets auth header + body injected
# curl https://api.openai.com/...  -> gets auth header injected
# curl https://httpbin.org/...     -> allowed, no injection
# curl https://evil.com/...        -> BLOCKED by allowedDomains firewall

result = await sandbox.process.exec({
    "command": "curl -s https://api.stripe.com/v1/charges",
    "wait_for_completion": True,
})
print(result.logs)