Sandbox Firewall

Archil’s persistent sandboxes support defining a network policy to filter network egress from the sandbox. This is useful when running untrusted workloads, including agents.

To prevent platform abuse, network egress is limited to the Team plan and above. On the Developer plan, all network egress is denied. Sandboxes created on the Developer plan keep denying egress after an upgrade until you replace their policy.

The sandbox firewall operates on both the IP and transport layer, so you can filter both CIDR ranges and domains. To deny all network egress you can set the default to deny. On top of this, you can apply additional deny and allow rules to whitelist certain targets. For example:

import * as archil from "disk";

const sandbox = await archil.createSandbox({
  network: {
    egress: {
      default: "deny",
      allow: ["192.168.14.0/24", "*.github.com"],
    }
  }
});

Domain filtering

Domain filtering applies to all HTTP traffic (ports 80/443). HTTP/3 is blocked when domain filters or drain_on_pause selectors are in place. It validates SNI using the TLS ClientHello, the Host header, and the URI authority for every request. If any are denied, then the request will be rejected. To support this, our egress proxy must terminate TLS, so we install an “archil egress” proxy CA into every sandbox. Every process gets SSL_CERT_FILE, REQUESTS_CA_BUNDLE, CURL_CA_BUNDLE, and AWS_CA_BUNDLE pointing at the system bundle (/etc/ssl/certs/ca-certificates.crt) and NODE_EXTRA_CA_CERTS pointing at the Archil CA (/usr/local/share/ca-certificates/archil-egress.crt). Values you set yourself take precedence, so a custom bundle must include the Archil CA.

Credential brokering

For HTTP egress, we also support defining rules for transforming requests. This means that secret credentials can live outside the sandbox, so untrusted workloads cannot access them directly. For example, you can add API keys to outgoing HTTP requests so your sandbox never sees them:

import * as archil from "disk";

const sandbox = await archil.createSandbox({
  network: {
    egress: {
      default: "deny",
      allow: [{
        target: "api.github.com",
        transform: {
          headers: {
            Authorization: `Bearer ${process.env.GITHUB_TOKEN}`
          }
        }
      }],
    }
  }
});

Egress forwarding

Use forward_url on an allow rule to send matching requests to your own gateway. Applications inside the sandbox keep using the original API hostname, while your gateway can apply logging, usage limits, or request filtering before contacting the upstream service.

import * as archil from "disk";

const gatewayToken = process.env.EGRESS_GATEWAY_TOKEN;
if (!gatewayToken) throw new Error("Set EGRESS_GATEWAY_TOKEN before creating the sandbox");

const sandbox = await archil.createSandbox({
  network: {
    egress: {
      default: "deny",
      allow: [{
        target: "api.openai.com",
        forward_url: "https://gateway.example.com/archil",
        transform: {
          headers: {
            Authorization: `Bearer ${gatewayToken}`,
          },
        },
      }],
    },
  },
});

With this policy, a request to https://api.openai.com/v1/responses?trace=1 is sent to https://gateway.example.com/archil/v1/responses?trace=1. Archil appends the original path and query to the gateway URL’s path prefix and streams the request body and response. Your gateway decides whether to call the original upstream or return its own response. The transform adds your gateway token before forwarding, so the gateway can authenticate the request without exposing the token to code inside the sandbox. Archil also overwrites these headers on forwarded requests:

Header	Value
`archil-forwarded-host`	Original request hostname, such as `api.openai.com`.
`archil-forwarded-scheme`	Original scheme: `http` or `https`.
`archil-forwarded-port`	Original port: `80` or `443`.
`archil-forwarded-path`	Original path and query, such as `/v1/responses?trace=1`.
`archil-sandbox-id`	ID of the sandbox making the request.

Use these headers to identify the original destination and sandbox. Authenticate with the gateway token; the metadata headers alone do not prove that a request came from Archil. Forwarding works with domain allow rules for HTTP on port 80 and HTTPS on port 443. HTTPS clients must trust the Archil egress CA. Deny rules still take precedence. See Create Sandbox for URL restrictions and Dynamic Updates to change an existing sandbox’s policy.

Dynamic Updates

A running sandbox’s complete network policy can be replaced with updateNetwork, and getNetwork returns the current policy. A new policy applies to new connections; existing connections stay open. For example you can:

initially pull data from an S3 bucket
deny all egress while an agent is running
run a verifier and upload evaluation results

import * as archil from "disk";

const sandbox = await archil.createSandbox({
  network: {
    egress: {
      default: "deny",
      allow: ["data-bucket.s3.us-east-1.amazonaws.com"],
    }
  }
});

// download data...

await sandbox.updateNetwork({
  egress: {
    default: "deny",
  }
});

// run agent...

await sandbox.updateNetwork({
  egress: {
    default: "deny",
    allow: ["result-bucket.s3.us-east-1.amazonaws.com"]
  }
});

// run verifier...

Draining requests before pause

To let in-flight requests to selected hosts finish before a sandbox pauses, list them in drain_on_pause when creating the sandbox:

import * as archil from "disk";

const sandbox = await archil.createSandbox({
  network: {
    egress: {
      default: "allow",
      drain_on_pause: ["*.anthropic.com", "api.openai.com"],
    }
  }
});

await sandbox.pause();

Each entry is a lowercase hostname pattern without a scheme, port, or path. * matches anywhere, "*" selects every host, and a leading *. excludes the apex domain. Selectors do not grant network access. When the sandbox pauses, new requests to selected hosts are held and active HTTP(S) responses, including streams, get up to ten minutes to finish before the snapshot is taken. Draining covers ports 80 and 443; clients should retry stale connections after resume. Set selectors at creation, since connections opened before a policy update are not intercepted.

Getting started

Compute

Concepts

Data Sources

Details

Administration

Protocols

Reference

Legal

Sandbox Firewall

Domain filtering

Credential brokering

Egress forwarding

Dynamic Updates

Draining requests before pause

​Domain filtering

​Credential brokering

​Egress forwarding

​Dynamic Updates

​Draining requests before pause

Domain filtering

Credential brokering

Egress forwarding

Dynamic Updates

Draining requests before pause