feat: add info on sandbox firewall

[vikram-blaxel]

Fixes ENG-3410

---

Note

Adds documentation for the sandbox firewall feature (firewall: { rulesets: ["proxy"] }) and corrects the precedence rule when both allowedDomains and forbiddenDomains are set (now states allowedDomains takes precedence).

^{Written by Mendral for commit f072998.}

[mendral-app]

🧪 Testing Guide

What this PR addresses

Adds documentation for a new sandbox firewall feature (firewall: { rulesets: ["proxy"] }) that enforces domain filtering at the network level—even for tools that bypass HTTP_PROXY/HTTPS_PROXY environment variables. Also corrects the precedence behavior when both allowedDomains and forbiddenDomains are set (changed from "forbiddenDomains takes precedence" to "allowedDomains takes precedence"), adds a FirewallConfig type to the reference table, and adds a changelog entry.

Steps to verify

1. Proxy-domains page (Sandboxes/Proxy-domains.mdx):

   • Confirm the warning at the top now mentions "domain filter enforcement" with a working anchor link to the new section.
   • Scroll to the new "Domain filter enforcement" section — verify the TypeScript and Python code examples render correctly in the CodeGroup.
   • Confirm the precedence note now reads "allowedDomains takes precedence" (not forbiddenDomains).
   • Click the #domain-filter-enforcement anchor link from the warning — it should scroll to the correct section.

2. Proxy reference page (Sandboxes/Proxy.mdx):

   • Verify the reference table now includes a row for firewall (FirewallConfig type).
   • Verify the new FirewallConfig sub-table renders with the rulesets field description.
   • Confirm the forbiddenDomains description now says "allowedDomains takes precedence."

3. Changelog (changelog.mdx):

   • Verify a new entry dated 2026-06-13 titled "Proxy-based firewall support" appears.
   • Confirm it doesn't create a rendering issue with the existing 2026-06-13 entry below it (two entries with the same date label).

What to verify (expected behavior)

• All pages build and render without errors (no broken MDX syntax).
• Anchor links resolve correctly within the proxy-domains page.
• Code examples in the new section display proper syntax highlighting for both TypeScript and Python tabs.
• The precedence correction (allowedDomains > forbiddenDomains) is consistent across both files where it's mentioned.

Note

Posted by PR Testing Guide · Tag @mendral-app with feedback.

[mendral-app]

🔀 Interaction Flow: Sandbox Firewall Enforcement

Based on the changes in this PR, here's how the domain filter enforcement interacts with sandbox components:

sequenceDiagram
    participant Client as SDK Client
    participant API as Blaxel API
    participant Sandbox as Sandbox Instance
    participant Firewall as Network Firewall
    participant Proxy as Blaxel Proxy
    participant Ext as External Domain

    Client->>API: createIfNotExists(network config)
    Note over Client,API: firewall: { rulesets: ["proxy"] }<br/>allowedDomains: ["httpbin.org"]

    API->>Sandbox: Provision with firewall rules
    API->>Firewall: Apply ruleset "proxy"
    Note over Firewall: Forces all outbound traffic<br/>through proxy at network level

    Sandbox->>Ext: Outbound request (any tool)
    Firewall-->>Proxy: Intercept & redirect traffic
    
    alt Domain in allowedDomains
        Proxy->>Ext: Forward request
        Ext-->>Proxy: Response
        Proxy-->>Sandbox: Response
    else Domain not allowed / in forbiddenDomains
        Proxy--xSandbox: Block request
    end

Loading

Summary

This PR documents the new firewall configuration option for sandboxes:

• Without firewall enforcement (existing behavior): Domain filtering relies on tools respecting HTTP_PROXY/HTTPS_PROXY env vars — tools that bypass these are unfiltered.
• With firewall: { rulesets: ["proxy"] } (new): All outbound traffic is forced through the proxy at the network level, regardless of whether tools honor proxy env vars.

Files changed:

File	Change
Sandboxes/Proxy-domains.mdx	Added "Domain filter enforcement" section with code examples
Sandboxes/Proxy.mdx	Added FirewallConfig to the API reference table
changelog.mdx	Added changelog entry for proxy-based firewall support

Note

Posted by PR Sequence Diagram · Tag @mendral-app with feedback.

[mendral-app]

📋 Created Linear issue ENG-3410 — status: In Progress

• Assignee: vvaswani@blaxel.ai
• Labels: Doc, Sandox
• Estimate: S (3 files, 55 lines changed)
• PR linked: ✅ Issue will auto-close when this PR merges

Note: Branch prefix pm- doesn't match any Linear team (only ENG exists) — issue created under ENG.

Auto-created because no Linear reference was found in the PR title, description, or branch name.

Note

Posted by Linear Issue Enforcer · Tag @mendral-app with feedback.

[mendral-app]

LGTM

Previous review had no actionable comments. The new commit (f072998) corrects the precedence semantics from "forbiddenDomains takes precedence" to "allowedDomains takes precedence" consistently across both Proxy-domains.mdx and Proxy.mdx. No correctness or security issues in the documentation changes.

_{Tag @mendral-app with feedback or questions. View session}

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
blaxel	🟢 Ready	View Preview	Jun 25, 2026, 4:37 PM