> ## Documentation Index > Fetch the complete documentation index at: https://docs.blaxel.ai/llms.txt > Use this file to discover all available pages before exploring further. # Proxy > Route outbound sandbox traffic through Blaxel's platform proxy with man-in-the-middle (MITM) header/body injection and secrets, and configure 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](./Proxy-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](./Proxy-domains)** - the Blaxel proxy controls which external domains the sandbox can reach. Proxy and network configuration is set at sandbox creation time and **cannot be updated after the sandbox has been created**. To change the configuration (e.g. rotate a secret, add a new routing rule, or update the allowlist), you must create a new sandbox. Support for in-place updates is coming soon. ## 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 Standard HTTP clients work transparently: `curl`, `wget`, `git`, `pip`, `npm`, Node.js `https`, Python `requests`, etc. 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 TypeScript theme={null} 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: [...], }, }, }); ``` ```python Python theme={null} 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, `forbiddenDomains` 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` / `dict` | Headers injected into matching requests. Values may contain `{{SECRET:name}}` references. | | `body` | `Record` / `dict` | JSON body fields injected into matching requests. Values may contain `{{SECRET:name}}` references. | | `secrets` | `Record` / `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 TypeScript theme={null} import { listRegions } from "@blaxel/core"; const { data: regions } = await listRegions({ throwOnError: true }); for (const r of regions) { console.log(`${r.name}: proxy=${r.proxyAvailable}`); } ``` ```python Python theme={null} 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, the following tools 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 | | Node.js `https` | HTTPS | Automatic via `HTTPS_PROXY` + `NODE_EXTRA_CA_CERTS` env vars | ## 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 the outbound JSON payload. User-sent fields take precedence if there's a key collision * **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 ## Full example: agent sandbox with proxy + firewall ```typescript TypeScript theme={null} 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); ``` ```python Python theme={null} 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) ```