Skip to content

feat: add info on sandbox firewall #642

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
vikram-blaxel wants to merge 3 commits into
base: main
Choose a base branch
from
Draft

feat: add info on sandbox firewall #642

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
9e49c0d
feat: add info about sandbox firewall
vikram-blaxel Jun 25, 2026
4a76f08
feat: add info about sandbox firewall
vikram-blaxel Jun 25, 2026
f072998
fix: update text
vikram-blaxel Jun 25, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 40 additions & 2 deletions Sandboxes/Proxy-domains.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ tag: "public preview"
Domain filtering lets you control which external domains a sandbox can reach. You can define an allowlist (only listed domains are reachable) or a denylist (all domains except listed ones are reachable). Domain filtering and proxy routing are **independent configurations** — you do not need to duplicate domains across both. A domain can appear in the allowlist without having a proxy routing rule, and vice versa.

<Warning>
Domain filtering relies on the sandbox's tools and libraries respecting the standard proxy environment variables (`HTTP_PROXY`, `HTTPS_PROXY`). Traffic from tools that ignore these variables will not be filtered. Routing-level enforcement is planned for a future release.
Domain filtering relies on the sandbox's tools and libraries respecting the standard proxy environment variables (`HTTP_PROXY`, `HTTPS_PROXY`). Traffic from tools that ignore proxy environment variables will not be filtered unless [domain filter enforcement](#domain-filter-enforcement) is enabled.
</Warning>

## Allowlist
Expand Down Expand Up @@ -79,7 +79,45 @@ await SandboxInstance.create({
</CodeGroup>

<Note>
When both `allowedDomains` and `forbiddenDomains` are set, `forbiddenDomains` takes precedence: a domain that appears in both lists will be blocked.
When both `allowedDomains` and `forbiddenDomains` are set, `allowedDomains` takes precedence: a domain that appears in both lists will be allowed.
</Note>

## Domain filter enforcement

By default, domain filtering depends on the sandbox's tools respecting `HTTP_PROXY` and `HTTPS_PROXY`. To enforce filtering even for tools that bypass those variables, add a `firewall` config with `rulesets: ["proxy"]`. This forces all outbound traffic to flow through the proxy at the network level.

<CodeGroup>

```typescript TypeScript
await SandboxInstance.createIfNotExists({
name: "enforced-sandbox",
image: "blaxel/base-image:latest",
region: "us-was-1",
network: {
firewall: { rulesets: ["proxy"] },
allowedDomains: ["httpbin.org"],
proxy: { routing: [] },
},
});
```

```python Python
await SandboxInstance.create_if_not_exists({
"name": "enforced-sandbox",
"image": "blaxel/base-image:latest",
"region": "us-was-1",
"network": {
"firewall": {"rulesets": ["proxy"]},
"allowedDomains": ["httpbin.org"],
"proxy": {"routing": []},
},
})
```

</CodeGroup>

<Note>
Currently, this feature is not enforced automatically by the platform when a proxy is configured. In a future release, it will be automatically enforced whenever a proxy is configured.
</Note>

## Firewall + proxy combined
Expand Down
9 changes: 8 additions & 1 deletion Sandboxes/Proxy.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -92,9 +92,16 @@ sandbox = await SandboxInstance.create({
| 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. |
| `forbiddenDomains` | `string[]` / `list[str]` | Denylist — all domains except these are reachable. Supports wildcards. If both are set, `allowedDomains` takes precedence. |
| `firewall` | `FirewallConfig` | Proxy firewall configuration. |
| `proxy` | `ProxyConfig` | Proxy routing and bypass configuration. |

### `FirewallConfig`

| Field | Type | Description |
|---|---|---|
| `rulesets` | `string[]` / `list[str]` | Domain filtering rules to apply. Set to `["proxy"]` to force all sandbox outbound traffic through the Blaxel proxy. |

### `ProxyConfig`

| Field | Type | Description |
Expand Down
8 changes: 8 additions & 0 deletions changelog.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,14 @@ The SDKs can now clear a sandbox's expiration rules without recreating it. Pass

<Update label="2026-06-13">

### Proxy-based firewall support

Sandboxes can now enforce domain filtering at the network level.

</Update>

<Update label="2026-06-13">

### Refreshed Billing Explorer experience

<Frame>
Expand Down