Networking

See Networking for conceptual overview and TLS Interception for TLS proxy details.

Network

Frozen dataclass for sandbox network configuration. Use the class method presets for common cases, or construct directly with custom options.

Network(
    policy: str | NetworkPolicy | None = None,
    ports: Mapping[int, int] = {},
    deny_domains: tuple[str, ...] = (),
    deny_domain_suffixes: tuple[str, ...] = (),
    dns: DnsConfig | None = None,
    tls: TlsConfig | None = None,
    max_connections: int | None = None,
    trust_host_cas: bool | None = None,
)

DnsConfig

Frozen dataclass for DNS interception settings.

DnsConfig(
    rebind_protection: bool = True,
    nameservers: tuple[str, ...] = (),
    query_timeout_ms: int | None = None,
)

Network.none()

@classmethod
def none() -> Network

Deny all traffic. No network interface is created -- the guest is fully offline. exec and fs still work since they use the host-guest channel, not the network.

Returns

Network.public_only()

@classmethod
def public_only() -> Network

Block private address ranges and cloud metadata endpoints. Allow everything else. This is the default policy.

Returns

Network.allow_all()

@classmethod
def allow_all() -> Network

Unrestricted network access, including to private addresses and the host machine.

Returns

Types

NetworkPolicy

Frozen dataclass for a custom network policy. Two per-direction defaults plus an ordered list of rules evaluated first-match-wins per direction.

NetworkPolicy(
    default_egress: Action = Action.DENY,
    default_ingress: Action = Action.ALLOW,
    rules: tuple[Rule, ...] = (),
)

The defaults are asymmetric to preserve today's behavior: egress falls through to deny (today's public_only reachability when paired with the implicit allow public rule), ingress falls through to allow (today's unfiltered published-port behavior). See the defaults rationale.

Rule

Frozen dataclass for a single network policy rule.

Rule(
    action: Action,
    direction: Direction = Direction.EGRESS,
    destination: str | None = None,
    protocol: Protocol | None = None,
    port: int | str | None = None,
)

Ingress rules carrying ICMP protocols are rejected at sandbox creation: publisher.rs has no inbound ICMP path, so the rule would be dead code. Use Direction.EGRESS for ICMP allow/deny.

Rule.allow()

@classmethod
def allow(
    *,
    direction: Direction = Direction.EGRESS,
    protocol: Protocol | None = None,
    port: int | str | None = None,
    destination: str | None = None,
) -> Rule

Create a rule that permits matching traffic.

Parameters

Returns

Rule.deny()

@classmethod
def deny(
    *,
    direction: Direction = Direction.EGRESS,
    protocol: Protocol | None = None,
    port: int | str | None = None,
    destination: str | None = None,
) -> Rule

Create a rule that blocks matching traffic.

Parameters

Returns

TlsConfig

Frozen dataclass for TLS interception settings within Network.

TlsConfig(
    bypass: tuple[str, ...] = (),
    verify_upstream: bool = True,
    intercepted_ports: tuple[int, ...] = (443,),
    block_quic: bool = False,
    ca_cert: str | None = None,
    ca_key: str | None = None,
    ca_cn: str | None = None,
)

Action

String enum (StrEnum) for policy actions.

Direction

String enum for traffic direction.

Protocol

String enum for network protocols in policy rules.

PortProtocol

String enum for port-level protocol selection.

DestGroup

String enum for well-known destination groups used in Rule.destination.