Networking

OpenSandbox provides comprehensive networking capabilities for sandboxes, including ingress routing to access services running inside sandboxes and egress control to restrict outbound network access.

Architecture

OpenSandbox networking consists of two main components:

Ingress Gateway

Routes external traffic to sandbox services via HTTP/HTTPS endpoints

Egress Control

Enforces network policies to restrict outbound traffic from sandboxes

Ingress routing

The Ingress Gateway provides HTTP/HTTPS access to services running inside sandboxes.

How it works

Service binding: When you create a sandbox, you can expose ports
Dynamic routing: The gateway creates routes based on sandbox ID and port
Endpoint generation: Get public URLs via sandbox.get_endpoint(port)
Traffic forwarding: Requests are proxied to the sandbox container

Getting endpoints

Retrieve the public URL for a service running in a sandbox:

Python
JavaScript
Kotlin

# Start a web server in the sandbox
await sandbox.commands.run_background(
    "python -m http.server 8000",
    working_dir="/workspace"
)

# Get the public endpoint
endpoint = await sandbox.get_endpoint(8000)
print(f"Access at: {endpoint}")
# https://api.opensandbox.io/sandboxes/sb-abc123/port/8000

// Start a web server
await sandbox.commands.runBackground(
  'python -m http.server 8000',
  { workingDir: '/workspace' }
);

// Get endpoint
const endpoint = await sandbox.getEndpoint(8000);
console.log(`Access at: ${endpoint}`);

// Start web server
sandbox.commands.runBackground(
    "python -m http.server 8000",
    workingDir = "/workspace"
)

// Get endpoint
val endpoint = sandbox.getEndpoint(8000)
println("Access at: $endpoint")

Routing modes

The Ingress Gateway supports multiple routing strategies:

URI-based routing
Header-based routing
Wildcard subdomain

Routes based on URL path:Format: https://domain/sandboxes/{sandboxId}/port/{port}Configuration:

[ingress]
mode = "uri"
domain = "api.opensandbox.io"

Example: https://api.opensandbox.io/sandboxes/sb-123/port/8000

Routes based on HTTP headers:Required headers:

X-OpenSandbox-Id: {sandboxId}
X-OpenSandbox-Port: {port}

Configuration:

[ingress]
mode = "header"
domain = "api.opensandbox.io"

Example:

curl -H "X-OpenSandbox-Id: sb-123" \
     -H "X-OpenSandbox-Port: 8000" \
     https://api.opensandbox.io

Routes based on subdomain:Format: https://{sandboxId}.{domain}Configuration:

[ingress]
mode = "wildcard"
domain = "sandboxes.opensandbox.io"

Example: https://sb-123.sandboxes.opensandbox.io

Requires wildcard DNS configuration (*.sandboxes.opensandbox.io)

WebSocket support

The Ingress Gateway supports WebSocket connections for real-time applications:

# Start a WebSocket server
await sandbox.commands.run_background(
    "python websocket_server.py",
    working_dir="/workspace"
)

endpoint = await sandbox.get_endpoint(8080)
# ws://api.opensandbox.io/sandboxes/sb-123/port/8080

Use cases:

VNC access for desktop environments
Real-time collaboration tools
Live terminal sessions
Interactive debugging

Egress control

The Egress Control component restricts outbound network access from sandboxes using FQDN-based policies.

Network policies

Define allowed or denied domains when creating a sandbox:

Deny by default
Allow by default

from opensandbox.models import NetworkPolicy, EgressRule

sandbox = await Sandbox.create(
    "python:3.11",
    network_policy=NetworkPolicy(
        egress=[
            EgressRule(domain="*.pypi.org", action="allow"),
            EgressRule(domain="github.com", action="allow"),
            EgressRule(domain="*", action="deny")
        ]
    )
)

This sandbox can only access PyPI and GitHub.

sandbox = await Sandbox.create(
    "python:3.11",
    network_policy=NetworkPolicy(
        egress=[
            EgressRule(domain="*.internal.company.com", action="deny"),
            EgressRule(domain="*", action="allow")
        ]
    )
)

This sandbox can access everything except internal company domains.

Policy rules

domain

string

required

Domain pattern with wildcard support:

example.com - Exact match
*.example.com - All subdomains
* - All domains (catch-all)

action

string

required

Action to take: allow or deny

priority

number

Rule priority (lower = higher priority). Defaults to order in array.

How egress control works

The egress sidecar intercepts DNS queries and network traffic:

DNS interception

The sidecar runs a DNS proxy that intercepts all DNS queries from the sandbox

Policy evaluation

Each DNS query is matched against the network policy rules

Traffic filtering

Allowed domains are resolved normally; denied domains return NXDOMAIN

nftables enforcement

IP-based rules are configured using nftables for additional enforcement

Deployment modes

Docker sidecar
Kubernetes DaemonSet

The egress sidecar runs as a separate container sharing the network namespace:

[docker]
enable_egress_sidecar = true
egress_sidecar_image = "opensandbox/egress:v1.0.0"

Resource impact:

CPU: ~10m (0.01 core)
Memory: ~50 MiB

Deploy as a DaemonSet for cluster-wide egress control:

apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: opensandbox-egress
spec:
  selector:
    matchLabels:
      app: opensandbox-egress
  template:
    spec:
      hostNetwork: true
      containers:
      - name: egress
        image: opensandbox/egress:v1.0.0

Network isolation

Docker networking modes

Host mode
Bridge mode

Sandbox uses the host’s network stack:

[docker]
network_mode = "host"

Pros: Better performance, simpler port access Cons: No network isolation, port conflictsUse case: Single-tenant environments, development

Sandbox uses Docker bridge networking:

[docker]
network_mode = "bridge"

Pros: Network isolation, no port conflicts Cons: Requires ingress gateway for external accessUse case: Multi-tenant production environments

Kubernetes network policies

In Kubernetes, use NetworkPolicy for pod-level isolation:

apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: sandbox-isolation
spec:
  podSelector:
    matchLabels:
      sandbox.opensandbox.io/managed: "true"
  policyTypes:
  - Ingress
  - Egress
  ingress:
  - from:
    - namespaceSelector:
        matchLabels:
          name: opensandbox-system
  egress:
  - to:
    - namespaceSelector: {}
    ports:
    - protocol: TCP
      port: 53  # DNS

Security considerations

Important: Network policies are enforced at the DNS and IP layers. Sandboxes with root access can potentially bypass these restrictions. For maximum security:

Drop Linux capabilities (CAP_NET_RAW, CAP_NET_ADMIN)
Use read-only root filesystems
Apply seccomp profiles
Run containers as non-root users

Recommended security configuration

from opensandbox.models import NetworkPolicy, SecurityContext

sandbox = await Sandbox.create(
    "python:3.11",
    network_policy=NetworkPolicy(
        egress=[
            EgressRule(domain="*.pypi.org", action="allow"),
            EgressRule(domain="*", action="deny")
        ]
    ),
    security_context=SecurityContext(
        capabilities_drop=["NET_RAW", "NET_ADMIN"],
        read_only_root_filesystem=True,
        run_as_non_root=True
    )
)

Common use cases

Web application testing

Expose web apps for manual or automated testing:

await sandbox.commands.run_background("npm start")
endpoint = await sandbox.get_endpoint(3000)
# Run Playwright tests against endpoint

Remote development

Access VS Code Server or Jupyter Lab:

await sandbox.commands.run_background(
    "code-server --bind-addr 0.0.0.0:8080"
)
endpoint = await sandbox.get_endpoint(8080)
# Open in browser

Restricted AI code execution

Allow AI-generated code to install packages but block other network access:

sandbox = await Sandbox.create(
    "python:3.11",
    network_policy=NetworkPolicy(
        egress=[
            EgressRule(domain="pypi.org", action="allow"),
            EgressRule(domain="*.pypi.org", action="allow"),
            EgressRule(domain="*", action="deny")
        ]
    )
)

VNC desktop access

Access full desktop environments via VNC:

await sandbox.commands.run_background(
    "vncserver -geometry 1920x1080 -depth 24"
)
endpoint = await sandbox.get_endpoint(5900)
# Connect with VNC client

Troubleshooting

Cannot access sandbox endpoint

Symptoms: 502 Bad Gateway or connection refusedSolutions:

Verify the service is running: await sandbox.commands.run("curl localhost:8000")
Check the port number is correct
Ensure the service binds to 0.0.0.0, not 127.0.0.1
Wait for service startup (add health check)

Egress policy not working

Symptoms: Sandbox can access blocked domainsSolutions:

Verify egress sidecar is enabled in config
Check sidecar container is running: docker ps
Review policy rule order (first match wins)
Drop NET_RAW capability to prevent raw socket access

WebSocket connections fail

Symptoms: WebSocket upgrade failsSolutions:

Ensure ingress gateway supports WebSocket (OpenSandbox does)
Check for proxies that don’t support WebSocket
Verify the application listens on the correct port

Ingress component

Deep dive into ingress gateway architecture

Egress component

Learn about egress control implementation

Security

Security best practices for networking

Configuration

Configure networking options

Get Started

Core Concepts

Deployment

SDKs

Components

Use Cases

Operations

Architecture

Ingress Gateway

Egress Control

Ingress routing

How it works

Getting endpoints

Routing modes

WebSocket support

Egress control

Network policies

Policy rules

How egress control works

Deployment modes

Network isolation

Docker networking modes

Kubernetes network policies

Security considerations

Recommended security configuration

Common use cases

Troubleshooting

Ingress component

Egress component

Security

Configuration

Build docs developers (and LLMs) love

Get Started

Core Concepts

Deployment

SDKs

Components

Use Cases

Operations

​Architecture

Ingress Gateway

Egress Control

​Ingress routing

​How it works

​Getting endpoints

​Routing modes

​WebSocket support

​Egress control

​Network policies

​Policy rules

​How egress control works

​Deployment modes

​Network isolation

​Docker networking modes

​Kubernetes network policies

​Security considerations

​Recommended security configuration

​Common use cases

​Troubleshooting

Ingress component

Egress component

Security

Configuration

Build docs developers (and LLMs) love

Architecture

Ingress routing

How it works

Getting endpoints

Routing modes

WebSocket support

Egress control

Network policies

Policy rules

How egress control works

Deployment modes

Network isolation

Docker networking modes

Kubernetes network policies

Security considerations

Recommended security configuration

Common use cases

Troubleshooting