# How to Configure Network Egress Controls with Specific Policies for Each Sandbox in OpenSandbox

> Learn how to configure network egress controls with specific policies for each sandbox in OpenSandbox. Enforce DNS and IP rules via nftables without elevated container capabilities.

- Repository: [Alibaba/OpenSandbox](https://github.com/alibaba/OpenSandbox)
- Tags: how-to-guide
- Published: 2026-03-08

---

**You configure per-sandbox network egress controls in OpenSandbox by defining a `networkPolicy` object in the CreateSandbox API request, which triggers automatic injection of an egress sidecar that enforces DNS and IP-level rules via nftables without requiring elevated capabilities in the application container.**

The **alibaba/OpenSandbox** repository implements granular outbound traffic filtering through an egress sidecar pattern. When you configure network egress controls, each sandbox can define its own whitelist or blacklist of domains and IPs through the `networkPolicy` field, enabling zero-trust network security for isolated workloads.

## How the Egress Sidecar Enforces Network Policies

OpenSandbox implements outbound restrictions by injecting an **egress sidecar** into the sandbox’s network namespace. According to the architecture documented in [`components/egress/README.md`](https://github.com/alibaba/OpenSandbox/blob/main/components/egress/README.md), the sidecar operates two enforcement layers:

### Layer 1: DNS Proxy Filtering

The sidecar runs a DNS proxy that intercepts all port 53 traffic within the namespace. When `OPENSANDBOX_EGRESS_MODE` is set to `dns` (the default), the proxy answers `NXDOMAIN` for denied domains, preventing resolution of restricted hostnames. This layer handles wildcard domain rules such as `*.example.com` by inspecting DNS queries before they reach external resolvers.

### Layer 2: nftables IP Filtering

When you set `OPENSANDBOX_EGRESS_MODE=dns+nft`, the sidecar enables IP-level blocking using nftables. As documented in [`components/egress/README.md`](https://github.com/alibaba/OpenSandbox/blob/main/components/egress/README.md), the sidecar dynamically adds resolved IPs of allowed domains to an nftables allow set while dropping all other outbound IP traffic. This provides defense-in-depth when DNS filtering alone is insufficient.

## Prerequisites for Enabling Egress Controls

Before you can configure per-sandbox policies, you must enable the egress sidecar in your server configuration.

### Configure the Egress Sidecar Image

In your server configuration file (typically `~/.sandbox.toml` or a custom config), specify the sidecar image in the `[egress]` block as shown in [`server/example.config.toml`](https://github.com/alibaba/OpenSandbox/blob/main/server/example.config.toml) (lines 34-45):

```toml
[egress]
image = "opensandbox/egress:v1.0.1"

```

The `opensandbox/egress` image contains the proxy binary and nftables logic required for policy enforcement.

### Enable Bridge Network Mode

The egress sidecar requires Docker bridge network mode. Ensure your server configuration sets `network_mode = "bridge"` as defined in [`server/example.config.toml`](https://github.com/alibaba/OpenSandbox/blob/main/server/example.config.toml). The sidecar runs with `CAP_NET_ADMIN` capability, while the application container executes without this privilege, maintaining least-privilege security.

## Defining Network Policies in the CreateSandbox API

The `networkPolicy` field in the CreateSandbox request declares your egress rules. As specified in the OpenAPI schema at [`specs/sandbox-lifecycle.yml`](https://github.com/alibaba/OpenSandbox/blob/main/specs/sandbox-lifecycle.yml) (lines 333-353), the policy structure contains:

- **`defaultAction`**: Either `allow` or `deny`, setting the baseline behavior for outbound traffic
- **`egress`**: An array of rules containing `action` (`allow` or `deny`) and `target` (domain or wildcard pattern)

When the server detects a `networkPolicy` in the request, it validates the configuration against the schema, pulls the sidecar image, and starts the container with `--cap-add=NET_ADMIN` in the same network namespace as the application container.

## Implementation Examples by Platform

### Python SDK Configuration

The OpenSandbox Python SDK accepts a `NetworkPolicy` object via the `network_policy` parameter. As documented in [`sdks/sandbox/python/README.md`](https://github.com/alibaba/OpenSandbox/blob/main/sdks/sandbox/python/README.md), you construct rules using `NetworkRule` instances:

```python
from datetime import timedelta
from opensandbox.models.sandboxes import NetworkPolicy, NetworkRule
from opensandbox.sdk import Sandbox, ConnectionConfig

cfg = ConnectionConfig(
    api_key="your-key",
    domain="api.opensandbox.io",
)

policy = NetworkPolicy(
    defaultAction="deny",
    egress=[
        NetworkRule(action="allow", target="pypi.org"),
        NetworkRule(action="allow", target="*.python.org"),
    ],
)

sandbox = await Sandbox.create(
    "python:3.11-slim",
    connection_config=cfg,
    timeout=timedelta(minutes=30),
    resource={"cpu": "2", "memory": "4Gi"},
    network_policy=policy,
)

```

### Raw HTTP API Request

For direct API integration, include the `networkPolicy` object in your JSON payload to the CreateSandbox endpoint:

```bash
curl -X POST http://localhost:8080/v1/sandboxes \
  -H "OPEN-SANDBOX-API-KEY: $OPEN_SANDBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "image": {"uri": "python:3.11"},
        "timeout": 3600,
        "resourceLimits": {"cpu": "500m", "memory": "512Mi"},
        "networkPolicy": {
          "defaultAction": "allow",
          "egress": [
            {"action": "deny", "target": "bad.example.com"},
            {"action": "deny", "target": "*.tracking.com"}
          ]
        }
      }'

```

### Manual Docker Deployment

For debugging or custom deployments, you can manually run the sidecar container:

```bash
docker pull opensandbox/egress:v1.0.1

docker run -d --name sandbox-egress \
  --cap-add=NET_ADMIN \
  opensandbox/egress:v1.0.1

```

Refer to [`components/egress/README.md`](https://github.com/alibaba/OpenSandbox/blob/main/components/egress/README.md) for the complete "Build & Run" command reference.

### Kubernetes Helm Configuration

When deploying via the OpenSandbox Helm chart (`charts/opensandbox-controller`), set the sidecar image in your [`values.yaml`](https://github.com/alibaba/OpenSandbox/blob/main/values.yaml) as shown in [`kubernetes/charts/opensandbox-controller/values.yaml`](https://github.com/alibaba/OpenSandbox/blob/main/kubernetes/charts/opensandbox-controller/values.yaml) (lines 129-131):

```yaml
egress:
  image: "opensandbox/egress:v1.0.1"

```

The controller automatically injects the sidecar into Pods carrying the `networkPolicy` annotation.

## Runtime Configuration Options

The egress sidecar behavior is controlled through environment variables defined in [`components/egress/README.md`](https://github.com/alibaba/OpenSandbox/blob/main/components/egress/README.md):

- **`OPENSANDBOX_EGRESS_MODE`**: Set to `dns` (default) for DNS-only filtering or `dns+nft` for additional IP-level nftables enforcement
- **`OPENSANDBOX_EGRESS_API_ADDR`**: HTTP API address for the sidecar
- **`OPENSANDBOX_EGRESS_TOKEN`**: Authentication token for sidecar API access

To enable IP-level blocking, start the server with:

```bash
export OPENSANDBOX_EGRESS_MODE=dns+nft
opensandbox-server

```

## Security Considerations and Limitations

As documented in [`oseps/0001-fqdn-based-egress-control.md`](https://github.com/alibaba/OpenSandbox/blob/main/oseps/0001-fqdn-based-egress-control.md), the sidecar implementation provides FQDN-based security without requiring `CAP_NET_ADMIN` in the application container. However, note that **IPv6 traffic is currently disabled** when the sidecar is injected, as noted in [`server/README.md`](https://github.com/alibaba/OpenSandbox/blob/main/server/README.md). Additionally, the sidecar is only injected when a sandbox explicitly requests a `networkPolicy`; sandboxes without this field maintain unrestricted outbound access.

## Summary

- **Network egress controls** in OpenSandbox rely on an injected sidecar that operates in the sandbox's network namespace with `CAP_NET_ADMIN` privileges.
- Configure the sidecar image in `[egress]` blocks within [`server/example.config.toml`](https://github.com/alibaba/OpenSandbox/blob/main/server/example.config.toml) before enabling policies.
- Define per-sandbox rules using the `networkPolicy` field in `CreateSandbox` requests, specifying `defaultAction` and `egress` rule arrays.
- Enforcement occurs at Layer 1 (DNS proxy) by default, with optional Layer 2 (nftables) filtering when `OPENSANDBOX_EGRESS_MODE=dns+nft`.
- The application container requires no additional Linux capabilities, maintaining security isolation.

## Frequently Asked Questions

### What happens if I omit the networkPolicy field when creating a sandbox?

If you do not include the `networkPolicy` field in your `CreateSandbox` request, the sandbox runs with unrestricted outbound network access. The egress sidecar is only injected when a policy is explicitly requested, ensuring backward compatibility and minimal overhead for sandboxes that do not require egress filtering.

### Does my application container need NET_ADMIN capabilities?

No. According to the injection logic described in [`server/README.md`](https://github.com/alibaba/OpenSandbox/blob/main/server/README.md), the egress sidecar container runs with `CAP_NET_ADMIN` while sharing the network namespace with the application container. Your application code executes without elevated networking capabilities, adhering to the principle of least privilege while still benefiting from fine-grained egress controls.

### How are wildcard domains like *.example.com handled?

The DNS proxy layer resolves wildcard patterns by intercepting all port 53 traffic, as implemented in the sidecar architecture. When Layer 2 nftables enforcement is enabled (`dns+nft` mode), the sidecar automatically adds the resolved IP addresses of matching domains to the nftables allow set, ensuring that wildcard rules work correctly at both the DNS and IP filtering layers.

### Can I use IPv6 with the egress sidecar enabled?

No. As noted in the server documentation at [`server/README.md`](https://github.com/alibaba/OpenSandbox/blob/main/server/README.md), IPv6 traffic is explicitly disabled when the egress sidecar is injected into the sandbox network namespace. This limitation is part of the current implementation and should be considered when architecting network policies for sandboxes requiring egress controls.