Network Access

Control which hosts a sandbox can reach over the network. Egress rules are defined in SandboxConfig.egress and evaluated at request time — the first matching rule wins.

Default behavior

When egress is empty or omitted, all outbound traffic is denied. You must explicitly allow every destination your sandbox needs to reach.

index.ts

import { getOrCreateSandbox } from "hive";

// No egress rules — all outbound traffic is denied
const sandbox = await getOrCreateSandbox("my-sandbox", {
  fs: [{ backend: "local", mount: "/workspace", acls: [{ path: "/workspace/**", access: "rw" }] }],
});

import { getOrCreateSandbox } from "hive";

// No egress rules — all outbound traffic is denied
const sandbox = await getOrCreateSandbox("my-sandbox", {
  fs: [{ backend: "local", mount: "/workspace", acls: [{ path: "/workspace/**", access: "rw" }] }],
});

To open all outbound traffic, allow the wildcard host:

index.ts

const sandbox = await getOrCreateSandbox("my-sandbox", {
  egress: [{ access: "allow", host: "*" }],
  ...
});

const sandbox = await getOrCreateSandbox("my-sandbox", {
  egress: [{ access: "allow", host: "*" }],
  ...
});

Allowing specific hosts

Add an entry to egress for each destination you want to permit. You can narrow rules further by port, HTTP method, or path:

index.ts

const sandbox = await getOrCreateSandbox("my-sandbox", {
  fs: [{ backend: "local", mount: "/workspace", acls: [{ path: "/workspace/**", access: "rw" }] }],
  egress: [
    { access: "allow", host: "api.anthropic.com" },
    { access: "allow", host: "pypi.org", ports: [443] },
    { access: "allow", host: "api.github.com", methods: ["GET", "POST"] },
    { access: "allow", host: "api.example.com", paths: ["/v1/*"] },
  ],
});

const sandbox = await getOrCreateSandbox("my-sandbox", {
  fs: [{ backend: "local", mount: "/workspace", acls: [{ path: "/workspace/**", access: "rw" }] }],
  egress: [
    { access: "allow", host: "api.anthropic.com" },
    { access: "allow", host: "pypi.org", ports: [443] },
    { access: "allow", host: "api.github.com", methods: ["GET", "POST"] },
    { access: "allow", host: "api.example.com", paths: ["/v1/*"] },
  ],
});

Field	Type	Description
`host`	`string`	Hostname to match. Supports `*` as a wildcard (see below).
`ports`	`number[]`	Restrict to specific destination ports. Omit to allow all ports.
`methods`	`string[]`	Restrict to specific HTTP methods. Omit to allow all methods.
`paths`	`string[]`	Restrict to specific URL path patterns (glob). Omit to allow all paths.

Unmatched requests are denied — there is no implicit fallthrough.

Wildcard host patterns

Use * as a prefix to match a hostname and all its subdomains:

index.ts

egress: [
  { access: "allow", host: "*.pypi.org" }, // matches files.pypi.org, pypi.org subdomains
  { access: "allow", host: "api.anthropic.com" }, // exact match only
]

egress: [
  { access: "allow", host: "*.pypi.org" }, // matches files.pypi.org, pypi.org subdomains
  { access: "allow", host: "api.anthropic.com" }, // exact match only
]

Use * alone to allow all outbound traffic:

index.ts

egress: [{ access: "allow", host: "*" }]

egress: [{ access: "allow", host: "*" }]

Injecting credentials with override

Use override to attach headers to every outbound request that matches the rule. The agent running inside the sandbox cannot read the injected values back — they are applied transparently by the network proxy.

index.ts

const sandbox = await getOrCreateSandbox("my-sandbox", {
  egress: [{
    access: "allow",
    host: "api.finnhub.io",
    override: {
      headers: { "X-Finnhub-Token": process.env.FINNHUB_API_KEY! },
    },
  }],
  ...
});

const sandbox = await getOrCreateSandbox("my-sandbox", {
  egress: [{
    access: "allow",
    host: "api.finnhub.io",
    override: {
      headers: { "X-Finnhub-Token": process.env.FINNHUB_API_KEY! },
    },
  }],
  ...
});

This is useful for giving an agent access to a third-party API without embedding the key in the agent's context or environment.

Updating egress at runtime

Call sandbox.applyConfig() to replace the egress rules while the sandbox is running. Read the current config first with sandbox.getConfig() to preserve other settings:

index.ts

await sandbox.applyConfig({
  ...(await sandbox.getConfig()),
  egress: [
    { access: "allow", host: "api.anthropic.com" },
  ],
});

await sandbox.applyConfig({
  ...(await sandbox.getConfig()),
  egress: [
    { access: "allow", host: "api.anthropic.com" },
  ],
});

The new rules take effect immediately. Any in-flight requests that have already been allowed are not interrupted.

Observing blocked requests

Subscribe to sandbox.getEventsStream() and filter for egress.request events with access: "denied" to see which outbound requests are being blocked:

index.ts

for await (const event of sandbox.getEventsStream()) {
  if (event.type === "egress.request" && event.access === "denied") {
    console.log("blocked:", event.host, event.method, event.path);
  }
}

for await (const event of sandbox.getEventsStream()) {
  if (event.type === "egress.request" && event.access === "denied") {
    console.log("blocked:", event.host, event.method, event.path);
  }
}

Field	Description
`event.host`	Destination hostname of the blocked request
`event.method`	HTTP method (e.g. `GET`, `POST`)
`event.path`	URL path of the blocked request
`event.access`	`"allowed"` or `"denied"`

See Audit Log for a full reference of event types.

Next: File Access