Sandbox Networking

Sandbox network policies control connections initiated by workloads inside a sandbox. Outbound internet access is allowed by default. Add a policy at creation time or update a running sandbox when you need to restrict its access. Network policies affect outbound traffic only. They do not change inbound access through exposed ports.

Policy Fields

boolean

default:true

Controls outbound internet access for destinations not covered by allowOut or denyOut. Set it to false for a default-deny policy.

string[]

Outbound destinations to allow. Entries can be IPv4 addresses, IPv4 CIDR ranges, exact domains, or wildcard domains such as *.example.com.

string[]

Outbound destinations to deny. Entries can be IPv4 addresses or IPv4 CIDR ranges. Domain entries are not supported in denyOut.

An empty policy is equivalent to:

{
  "allowInternetAccess": true,
  "allowOut": [],
  "denyOut": []
}

Rule Precedence

When allowOut and denyOut both match the same destination, allowOut takes precedence. For example:

{
  "allowInternetAccess": true,
  "allowOut": ["203.0.113.10"],
  "denyOut": ["203.0.113.0/24"]
}

203.0.113.10 is allowed because it matches both rules and allowOut wins.
Other addresses in 203.0.113.0/24 are blocked.
Destinations outside that range are allowed because allowInternetAccess is true.

A domain in allowOut requires a default-deny boundary: set allowInternetAccess to false or include 0.0.0.0/0 in denyOut. Hyperbrowser rejects the policy otherwise.

IPv4 addresses are normalized to /32 CIDRs, CIDRs are normalized to their network address, domains are lowercased, and duplicate entries are removed. IPv4 and CIDR rules match the destination across all ports and protocols. IPv6 policy targets are not currently supported.

Create With a Network Policy

The following policy blocks outbound internet access except for the exact domain api.github.com and the IPv4 address 1.1.1.1.

from hyperbrowser import Hyperbrowser

client = Hyperbrowser(api_key="YOUR_API_KEY")

sandbox = client.sandboxes.create(
    {
        "image_name": "python",
        "allow_internet_access": False,
        "allow_out": ["api.github.com", "1.1.1.1"],
    }
)

from hyperbrowser import Hyperbrowser
from hyperbrowser.models import CreateSandboxParams

client = Hyperbrowser(api_key="YOUR_API_KEY")

sandbox = client.sandboxes.create(
    CreateSandboxParams(
        image_name="python",
        allow_internet_access=False,
        allow_out=["api.github.com", "1.1.1.1"],
    )
)

hx vm create python \
  --allow-internet=false \
  --allow-out api.github.com \
  --allow-out 1.1.1.1

curl -X POST https://api.hyperbrowser.ai/api/sandbox \
  -H "x-api-key: $HYPERBROWSER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "imageName": "python",
    "allowInternetAccess": false,
    "allowOut": ["api.github.com", "1.1.1.1"]
  }'

To allow internet access by default while blocking selected networks, leave allowInternetAccess as true and add IPv4 or CIDR entries to denyOut.

Update a Running Sandbox

Update the policy without restarting the sandbox:

result = sandbox.update_network(
    {
        "allow_internet_access": False,
        "allow_out": ["api.github.com"],
        "deny_out": [],
    }
)

print(result.network)

from hyperbrowser.models import SandboxNetworkPolicy

result = sandbox.update_network(
    SandboxNetworkPolicy(
        allow_internet_access=False,
        allow_out=["api.github.com"],
        deny_out=[],
    )
)

print(result.network)

hx vm network set "$sandbox_id" \
  --allow-internet=false \
  --allow-out api.github.com

curl -X PUT \
  "https://api.hyperbrowser.ai/api/sandbox/$sandbox_id/network" \
  -H "x-api-key: $HYPERBROWSER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "allowInternetAccess": false,
    "allowOut": ["api.github.com"],
    "denyOut": []
  }'

The update endpoint uses patch semantics:

Omitted fields keep their current values.
A supplied allowOut or denyOut array replaces that entire list.
Supply an empty array to clear one list.

The Python SDK sends only fields supplied in the request. The CLI sends only the flags provided to hx vm network set.

Policy changes apply to new connections. Established connections may continue until they close.

Clear a Network Policy

Restore the default outbound policy and remove all allow and deny entries.

sandbox.clear_network()

hx vm network clear "$sandbox_id"

curl -X PUT \
  "https://api.hyperbrowser.ai/api/sandbox/$sandbox_id/network" \
  -H "x-api-key: $HYPERBROWSER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "allowInternetAccess": true,
    "allowOut": [],
    "denyOut": []
  }'

Sandbox create, get, and network-update responses include the effective policy under the network field.

Domain Rules

Domain entries are supported only in allowOut, and a policy containing one must have a default-deny boundary. Set allowInternetAccess to false or add 0.0.0.0/0 to denyOut.

example.com matches only example.com, not its subdomains.
*.example.com matches subdomains such as api.example.com, but not the apex example.com. Add both entries when you need both forms.
Domain rules apply to HTTP on port 80 and HTTPS on port 443. HTTPS matching uses the TLS server name. For other ports or protocols, allow the destination with an IPv4 or CIDR entry.
While domain rules are active, DNS permits A, AAAA, SVCB, and HTTPS lookups for allowed names and refuses lookups for other names.
Domain-based connections reject hostnames that resolve to loopback, private, carrier-grade NAT, or link-local addresses.

Domain rules require the application to send a hostname in the HTTP Host header or HTTPS TLS server name. Connections that do not expose a matching hostname need an IPv4 or CIDR allow entry.

Common Patterns

Block All Outbound Access

{
  "allowInternetAccess": false,
  "allowOut": [],
  "denyOut": []
}

Allow Only Selected Web Domains

{
  "allowInternetAccess": false,
  "allowOut": ["example.com", "*.example.com"],
  "denyOut": []
}

Block a Network With One Exception

Because allow rules take precedence, a narrow allow can override a broader deny:

{
  "allowInternetAccess": true,
  "allowOut": ["203.0.113.10"],
  "denyOut": ["203.0.113.0/24"]
}

Get Started

Sandbox

Base Images

Custom Images

Volumes

Local Filesystem

Policy Fields

Rule Precedence

Create With a Network Policy

Update a Running Sandbox

Clear a Network Policy

Domain Rules

Common Patterns

Block All Outbound Access

Allow Only Selected Web Domains

Block a Network With One Exception

​Policy Fields

​Rule Precedence

​Create With a Network Policy

​Update a Running Sandbox

​Clear a Network Policy

​Domain Rules

​Common Patterns

​Block All Outbound Access

​Allow Only Selected Web Domains

​Block a Network With One Exception

Policy Fields

Rule Precedence

Create With a Network Policy

Update a Running Sandbox

Clear a Network Policy

Domain Rules

Common Patterns

Block All Outbound Access

Allow Only Selected Web Domains

Block a Network With One Exception