Python SDK Networking reference

See Networking for network policies, DNS, TLS, and port publishing.

Network

Sandbox network configuration.

Network(
    policy: NetworkPolicy | None = None,
    ports: Mapping[int, int] | Sequence[PortBinding] = {},
    deny_domains: tuple[str, ...] = (),
    deny_domain_suffixes: tuple[str, ...] = (),
    dns: DnsConfig | None = None,
    tls: TlsConfig | None = None,
    strict: bool = True,
    ipv4_pool: str | None = None,
    ipv6_pool: str | None = None,
    nat64_prefixes: tuple[str, ...] = ("64:ff9b::/96",),
    max_tcp_connections: int | None = None,
    max_udp_connections: int | None = None,
    tcp_accept_queue_size: int | None = None,
    secret_violation_action: ViolationAction = ViolationAction.BLOCK_AND_LOG,
    http: HttpConfig | None = None,
)

Field	Type	Default	Description
`policy`	`NetworkPolicy \| None`	`None`	Concrete network policy
`ports`	`Mapping[int, int] \| Sequence[PortBinding]`	`{}`	Port mappings from host to guest. Mapping form binds TCP to `127.0.0.1`; `PortBinding` can set an explicit bind address or UDP
`deny_domains`	`tuple[str, ...]`	`()`	Deny egress to these exact domains. Each entry adds a `deny Domain("...")` policy rule that fires at DNS resolution (NXDOMAIN), TLS first-flight (SNI), and TCP egress (cache fallback). Prepended onto the policy so it takes precedence over later allow rules
`deny_domain_suffixes`	`tuple[str, ...]`	`()`	Deny egress to all subdomains of these suffixes. Adds `deny DomainSuffix("...")` rules; same enforcement layers as `deny_domains`
`dns`	`DnsConfig \| None`	`None`	DNS interception configuration
`tls`	`TlsConfig \| None`	`None`	TLS interception configuration
`strict`	`bool`	`True`	Require hostname-based policy allows to use an inspectable request authority. Plain HTTP exposes that authority in `Host`; HTTPS only exposes it when TLS interception is enabled and not bypassed. Without that visibility, strict mode denies HTTPS that would otherwise be allowed only by a hostname rule.
`ipv4_pool`	`str \| None`	`None`	IPv4 pool used for per-sandbox `/30` guest subnets. Defaults to `172.16.0.0/12`
`ipv6_pool`	`str \| None`	`None`	IPv6 pool used for per-sandbox `/64` guest prefixes. Defaults to `fd42:6d73:62::/48`

network.tcp_accept_queue_size

int \| None · Default: None (1,024) How many not-yet-accepted connections each published TCP port’s host listener queues, from 1 to 2,147,483,647. Connections arriving while the queue is full never reach the sandbox, so raise this when a burst of parallel connections, such as a reverse proxy fanning out one page load, exceeds it. The host kernel caps the effective depth at its own somaxconn (4,096 by default on Linux, 128 on macOS). Sandbox.restore(..., tcp_accept_queue_size=n) applies it to the listeners a restored child publishes.

network.nat64_prefixes

tuple[str, ...] · Default: ("64:ff9b::/96",) NAT64 /96 prefixes for policy classification. Destinations inside these prefixes are also evaluated by their embedded IPv4 address. Pass this field by keyword. Custom or empty prefix lists are supported only for local sandboxes; cloud creation rejects them.

max_udp_connections

Network(max_udp_connections=512) sets the runtime UDP relay session limit. Omission is unlimited in single-tenant mode and defaults to 1,024 in multi-tenant mode; zero explicitly selects unlimited. At a finite limit, a new session evicts the least recently active session. Sessions expire after 60 seconds of inactivity.

network.max_tcp_connections

max_connections remains a deprecated TCP-only alias. Specifying both names is an error. Either name can be combined with the UDP limit. int \| None · Default: None Maximum concurrent TCP connections. Zero selects unlimited. The same limits can be selected when restoring, without changing the captured guest interface:

restored = await Sandbox.restore(
    "saved", name="child", max_tcp_connections=64, max_udp_connections=128,
)

Omitted restore limits use destination defaults. restore_with_progress() accepts the same options; max_connections remains a deprecated TCP-only alias, and supplying both TCP names is an error.

Field	Type	Default	Description
`rate_limiter`	`NetworkRateLimiter \| None`	`None`	Ingress and egress rate limits
`secret_violation_action`	`ViolationAction`	`BLOCK_AND_LOG`	Sandbox-wide action when a secret placeholder reaches a disallowed host

network.http

HttpConfig | None · Default: None Denial responses are disabled by default. Set HttpConfig(deny_response=True) to enable readable 403 responses. Optionally set deny_message to customize the body; {host} names the blocked hostname. Setting a message alone does not enable responses. When enabled, None uses the built-in message and an empty string sends no body. Requires a supporting local runtime; cloud rejects enabling it.

from microsandbox import HttpConfig, Network

network = Network(http=HttpConfig(deny_response=True, deny_message="Blocked: {host}"))

Network.none()

@classmethod
def none() -> Network

Example

sb = await Sandbox.create("offline", image="python", network=Network.none())

Deny all traffic in both directions. The network interface remains present; exec and fs still work since they use the host-guest channel, not the network.

Returns

Network

Network configuration with deny defaults in both directions.

Network.from_profiles()

@classmethod
def from_profiles(*profiles: NetworkProfile) -> Network

Build a deny-by-default network configuration from PUBLIC, PRIVATE, and HOST profiles. Duplicate profiles are ignored, generated rules use canonical order, and gateway DNS is added automatically for every non-empty profile set.

from microsandbox import Network, NetworkProfile

network = Network.from_profiles(NetworkProfile.PUBLIC, NetworkProfile.PRIVATE)

Returns

Network

Network configuration containing the composed profiles.

Network.allow_all()

@classmethod
def allow_all() -> Network

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

Returns

Network

Unrestricted network configuration.

Rule

Used by NetworkPolicy(rules=…)

Frozen dataclass for a single network policy rule. Prefer the Rule.allow() / Rule.deny() class methods over the positional constructor.

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

Field	Type	Default	Description
`action`	`Action`	—	What to do when this rule matches
`direction`	`Direction`	`EGRESS`	Which evaluator considers this rule. `Direction.ANY` matches in either direction
`destination`	`str \| NetworkDestination \| None`	`None`	Target filter. Prefer typed `Destination` helpers; string shorthand also works (`DestGroup` values, exact IPs, domains, CIDR ranges, domain suffixes prefixed with `"."`, or `"*"` for any). Domain and suffix strings are validated at sandbox creation; invalid names raise `ValueError`
`protocol`	`Protocol \| None`	`None`	Protocol filter
`port`	`int \| str \| None`	`None`	Single port (`443`) or range (`"8000-9000"`)

Ingress rules carrying ICMP protocols are rejected at sandbox creation; the host has no inbound ICMP path. Use Direction.EGRESS for ICMP allow/deny. A NetworkPolicy is an ordered list of Rule values plus two per-direction defaults, evaluated first-match-wins per direction. The class methods below build rules; assemble them into NetworkPolicy(rules=(...)) and pass it as Network(policy=...).

from microsandbox import Action, Destination, NetworkPolicy, Protocol, Rule

policy = NetworkPolicy(
    default_egress=Action.DENY,
    default_ingress=Action.ALLOW,
    rules=(
        Rule.allow(protocol=Protocol.TCP, port=443, destination=Destination.ip("1.1.1.1")),
        Rule.deny(destination=Destination.domain("api.example.com")),
    ),
)

Rule order matters

The first matching rule wins, so a broad rule placed before a narrow one swallows it:

policy = NetworkPolicy(
    default_egress=Action.DENY,
    default_ingress=Action.ALLOW,
    rules=(
        Rule.allow(destination="10.0.0.0/8"),     # matches everything in 10.x
        Rule.deny(destination="10.0.0.5"),        # never reached
    ),
)

Put specific rules before general ones.

Rule.allow()

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

Example

from microsandbox import Destination, Protocol, Rule

r = Rule.allow(protocol=Protocol.TCP, port=443, destination=Destination.domain("api.example.com"))

Create a rule that permits matching traffic. All filters are keyword-only.

Parameters

directionDirection

Which evaluator considers the rule. Defaults to EGRESS.

protocolProtocol | None

Protocol filter.

portint | str | None

Single port (443) or range (“8000-9000”).

destinationstr | NetworkDestination | None

Target filter. Prefer the typed Destination helpers; string shorthand is also accepted.

Returns

Rule

An allow rule.

Rule.deny()

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

Create a rule that blocks matching traffic. Same keyword-only filters as allow().

Parameters

directionDirection

Which evaluator considers the rule. Defaults to EGRESS.

protocolProtocol | None

Protocol filter.

portint | str | None

Single port (0–65535) or inclusive port range such as 8000-9000. Invalid values and reversed ranges raise ValueError; omit the filter to match any port.

destinationstr | NetworkDestination | None

Target filter.

Returns

Rule

A deny rule.

Rule.allow_dns()

@classmethod
def allow_dns() -> tuple[Rule, Rule]

Example

from microsandbox import Action, DestGroup, Destination, NetworkPolicy, Protocol, Rule

policy = NetworkPolicy(
    default_egress=Action.DENY,
    rules=(
        *Rule.allow_dns(),
        Rule.allow(
            protocol=Protocol.TCP,
            port=443,
            destination=Destination.group(DestGroup.PUBLIC),
        ),
    ),
)

Allow plain DNS (UDP/53 and TCP/53) to the sandbox gateway, i.e. the in-process DNS forwarder. The standard one-liner for opening DNS under a deny-by-default policy. See DNS as egress for the underlying semantics. Returns the pair (udp_rule, tcp_rule) since this SDK’s Rule shape carries a single protocol; splat into NetworkPolicy.rules. DoT (TCP/853) is intentionally not included; add an explicit Rule.allow(destination=Destination.group(DestGroup.HOST), protocol=Protocol.TCP, port=853) if needed (and pair with TLS interception).

Rule.deny_dns()

@classmethod
def deny_dns() -> tuple[Rule, Rule]

Deny gateway UDP/53 and TCP/53. Place these rules before profile-generated rules to override their automatic DNS access.

Returns

tuple[Rule, Rule]

(udp_rule, tcp_rule) for DestGroup.HOST on port 53.

Destination

Returns NetworkDestination · used by Rule.allow() / Rule.deny()

Factory for typed NetworkDestination values.

Destination.any()

@staticmethod
def any() -> NetworkDestination

Match any destination.

Destination.ip()

@staticmethod
def ip(ip: str) -> NetworkDestination

Match an exact IPv4 or IPv6 address. Stored as /32 for IPv4 or /128 for IPv6.

Parameters

ipstr

IPv4 or IPv6 address.

Destination.cidr()

@staticmethod
def cidr(cidr: str) -> NetworkDestination

Match a CIDR range.

Parameters

cidrstr

CIDR notation, e.g. “10.0.0.0/8”.

Destination.domain()

@staticmethod
def domain(domain: str) -> NetworkDestination

Match an exact domain. Domain strings are validated at sandbox creation; invalid names raise ValueError.

Parameters

domainstr

Fully qualified domain name.

Destination.domain_suffix()

@staticmethod
def domain_suffix(suffix: str) -> NetworkDestination

Match the apex domain and all subdomains.

Parameters

suffixstr

Domain suffix, e.g. “.example.com”.

Destination.group()

@staticmethod
def group(group: DestGroup) -> NetworkDestination

Match a well-known DestGroup address group.

Parameters

groupDestGroup

Group keyword.

PortBinding

Used by Network(ports=…)

Frozen dataclass for a published host-to-guest port with an optional host bind address. Prefer the PortBinding.tcp() / PortBinding.udp() class methods.

PortBinding(
    host_port: int,
    guest_port: int,
    bind: str = "127.0.0.1",
    protocol: PortProtocol = PortProtocol.TCP,
)

Field	Type	Default	Description
`host_port`	`int`	—	Port on the host
`guest_port`	`int`	—	Port inside the sandbox
`bind`	`str`	`"127.0.0.1"`	Host address to bind. Use `0.0.0.0` for all IPv4 interfaces

binding.protocol

PortProtocol · Default: TCP Published port protocol PortBinding is a frozen dataclass for published ports that need an explicit host bind address or UDP. Prefer the protocol-specific constructors over building one by hand.

PortBinding.tcp(8001, 8001, bind="0.0.0.0")
PortBinding.udp(5353, 5353, bind="0.0.0.0")

Pass them to Network(ports=(...)). A plain dict[int, int] is also accepted for the common case, binding TCP to 127.0.0.1.

PortBinding.tcp()

@classmethod
def tcp(cls, host_port: int, guest_port: int, *, bind: str = "127.0.0.1") -> PortBinding

Publish a TCP port from the sandbox to the host.

Parameters

host_portint

Port on the host.

guest_portint

Port inside the sandbox.

bindstr

Host bind address. Defaults to 127.0.0.1; use 0.0.0.0 for all IPv4 interfaces.

Returns

PortBinding

A TCP port binding.

PortBinding.udp()

@classmethod
def udp(cls, host_port: int, guest_port: int, *, bind: str = "127.0.0.1") -> PortBinding

Publish a UDP port from the sandbox to the host.

Parameters

host_portint

Port on the host.

guest_portint

Port inside the sandbox.

bindstr

Host bind address. Defaults to 127.0.0.1.

Returns

PortBinding

A UDP port binding.

NetworkPolicy

Used by Network(policy=…)

Ordered rules with per-direction defaults.

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

Field	Type	Default	Description
`default_egress`	`Action`	`DENY`	Action when no egress-applicable rule matches
`default_ingress`	`Action`	`ALLOW`	Action when no ingress-applicable rule matches
`rules`	`tuple[Rule, ...]`	`()`	Rules evaluated first-match-wins per direction

Class methods none() and allow_all() construct terminal whole policies. from_profiles(profiles) composes NetworkProfile values with canonical ordering and automatic gateway DNS.

NetworkPolicy.none()

NetworkPolicy.none()

Deny all ingress and egress traffic

Returns

NetworkPolicy

NetworkPolicy.allow_all()

NetworkPolicy.allow_all()

Allow all ingress and egress traffic

Returns

NetworkPolicy

NetworkPolicy.from_profiles()

NetworkPolicy.from_profiles(profiles)

Compose the selected canonical network profiles

Returns

NetworkPolicy

Types

NetworkProfile

Member	Value	Description
`NetworkProfile.PUBLIC`	`"public"`	Public internet addresses
`NetworkProfile.PRIVATE`	`"private"`	Private/LAN ranges
`NetworkProfile.HOST`	`"host"`	Sandbox host gateway addresses

NetworkDestination

Produced by Destination helpers

Frozen dataclass produced by Destination helpers.

NetworkDestination(
    kind: NetworkDestinationKind,
    value: str | None = None,
)

Field	Type	Default	Description
kind	`NetworkDestinationKind`	-	Destination variant
value	`str \| None`	`None`	Variant value, omitted for `Destination.any()`

NetworkDestinationKind

Returned in NetworkDestination.kind

Network destination variant.

Member	Value	Description
`NetworkDestinationKind.ANY`	`"any"`	Any destination
`NetworkDestinationKind.IP`	`"ip"`	One IP address
`NetworkDestinationKind.CIDR`	`"cidr"`	One CIDR network
`NetworkDestinationKind.DOMAIN`	`"domain"`	One exact domain
`NetworkDestinationKind.DOMAIN_SUFFIX`	`"domain_suffix"`	A domain suffix and its subdomains
`NetworkDestinationKind.GROUP`	`"group"`	A well-known `DestGroup`

DnsConfig

Used by Network(dns=…)

Frozen dataclass for DNS interception settings. The value type of Network.dns; import it from microsandbox.types.

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

Field	Type	Default	Description
rebind_protection	`bool`	`True`	Block DNS responses resolving to private IPs
nameservers	`tuple[str, ...]`	`()`	Nameservers (`IP`, `IP:PORT`, `HOST`, or `HOST:PORT`). Overrides the host’s `/etc/resolv.conf` when set. Hostnames are resolved once at startup via the host’s OS resolver
query_timeout_ms	`int \| None`	`None`	Per-DNS-query timeout in milliseconds. Defaults to `5000`

TlsConfig

Used by Network(tls=…)

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,
    upstream_ca_certs: tuple[str, ...] = (),
    scoped_upstream_ca_certs: tuple[ScopedUpstreamCACert, ...] = (),
    scoped_verify_upstream: tuple[ScopedVerifyUpstream, ...] = (),
    ca_cert: str | None = None,
    ca_key: str | None = None,
    ca_cn: str | None = None,
)

Field	Type	Default	Description
bypass	`tuple[str, ...]`	`()`	Domains to skip interception. Use for domains with certificate pinning
verify_upstream	`bool`	`True`	Verify upstream server certificates. Set to `False` only for self-signed servers
intercepted_ports	`tuple[int, ...]`	`(443,)`	TCP ports where TLS interception is active
block_quic	`bool`	`False`	Block QUIC/HTTP3 (UDP) on intercepted ports, forcing TCP/TLS fallback
upstream_ca_certs	`tuple[str, ...]`	`()`	Paths to additional CA bundles trusted for every upstream host
scoped_upstream_ca_certs	`tuple[ScopedUpstreamCACert, ...]`	`()`	Host-pattern-scoped CA bundles trusted only for matching upstream hosts
scoped_verify_upstream	`tuple[ScopedVerifyUpstream, ...]`	`()`	Host-pattern-scoped upstream certificate verification overrides
ca_cert	`str \| None`	`None`	Path to a custom interception CA certificate PEM file
ca_key	`str \| None`	`None`	Path to a custom interception CA private key PEM file
ca_cn	`str \| None`	`None`	Common name for the generated interception CA

ScopedUpstreamCACert

dataclass

Used by TlsConfig(scoped_upstream_ca_certs=…)

A CA bundle trusted only for upstream hosts matching a pattern.

ScopedUpstreamCACert(
    pattern: str,
    path: str,
)

Field	Type	Description
pattern	`str`	Exact host or `*.suffix` wildcard
path	`str`	CA bundle path trusted for matching upstream hosts

ScopedVerifyUpstream

dataclass

Used by TlsConfig(scoped_verify_upstream=…)

A per-host override for upstream certificate verification.

ScopedVerifyUpstream(
    pattern: str,
    verify: bool,
)

Field	Type	Description
pattern	`str`	Exact host or `*.suffix` wildcard
verify	`bool`	Whether to verify certificates for matching upstream hosts

NetworkRateLimiter

dataclass

Used by Network.rate_limiter

Groups local network limits by traffic direction. An omitted direction is unlimited.

Field	Type	Description
egress	`RateLimiter` `\| None`	Guest-to-runtime rate limiter
ingress	`RateLimiter` `\| None`	Runtime-to-guest rate limiter

RateLimiter

dataclass

Held by NetworkRateLimiter

Limits bandwidth and packet rate for one traffic direction.

Field	Type	Description
bandwidth	`TokenBucket` `\| None`	Byte budget; one token per byte of frame data
ops	`TokenBucket` `\| None`	Packet budget; one token per network frame

TokenBucket

dataclass

Used by RateLimiter

Token-bucket configuration for one rate-limiter dimension.

Field	Type	Description
size	`int`	Bucket capacity in bytes or frames. Must be greater than zero
refill_time_ms	`int`	Time to refill `size` tokens. Must be greater than zero
one_time_burst	`int`	Extra startup-only tokens. Default: `0`

Action

Used by NetworkPolicy · Rule

Policy action.

Member	Value	Description
`Action.ALLOW`	`"allow"`	Permit the traffic
`Action.DENY`	`"deny"`	Drop the traffic silently

Direction

Used by Rule

String enum for traffic direction.

Member	Value	Description
`Direction.EGRESS`	`"egress"`	Traffic leaving the sandbox
`Direction.INGRESS`	`"ingress"`	Traffic entering the sandbox (via published ports)
`Direction.ANY`	`"any"`	Rule applies in either direction

Protocol

Used by Rule

String enum for network protocols in policy rules.

Member	Value	Description
`Protocol.TCP`	`"tcp"`	TCP traffic
`Protocol.UDP`	`"udp"`	UDP traffic
`Protocol.ICMPV4`	`"icmpv4"`	ICMPv4 traffic
`Protocol.ICMPV6`	`"icmpv6"`	ICMPv6 traffic

PortProtocol

Used by PortBinding

String enum for port-level protocol selection.

Member	Value	Description
`PortProtocol.TCP`	`"tcp"`	TCP port
`PortProtocol.UDP`	`"udp"`	UDP port

DestGroup

Used by Destination.group()

String enum for well-known destination groups used in Destination.group() or string-shorthand Rule.destination.

Member	Value	Description
`DestGroup.PUBLIC`	`"public"`	Complement of the named categories: every address not in any other group
`DestGroup.PRIVATE`	`"private"`	Private/RFC 1918 addresses + ULA + CGN (`10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `100.64.0.0/10`, `fc00::/7`)
`DestGroup.LOOPBACK`	`"loopback"`	Loopback addresses (`127.0.0.0/8`, `::1`); the guest’s own loopback, not the host. See the loopback-vs-host watch-out
`DestGroup.LINK_LOCAL`	`"link-local"`	Link-local addresses (`169.254.0.0/16`, `fe80::/10`) excluding metadata
`DestGroup.METADATA`	`"metadata"`	Cloud metadata endpoints (`169.254.169.254`)
`DestGroup.MULTICAST`	`"multicast"`	Multicast addresses (`224.0.0.0/4`, `ff00::/8`)
`DestGroup.HOST`	`"host"`	The host machine, reached via `host.microsandbox.internal`. This is the right group for “let the sandbox reach my host’s localhost”, not `"loopback"`

​Network

​network.tcp_accept_queue_size

​network.nat64_prefixes

​max_udp_connections

​network.max_tcp_connections

​network.http

​Network.none()

​Network.from_profiles()

​Network.allow_all()

​Rule

​Rule order matters

​Rule.allow()

​Rule.deny()

​Rule.allow_dns()

​Rule.deny_dns()

​Destination

​Destination.any()

​Destination.ip()

​Destination.cidr()

​Destination.domain()

​Destination.domain_suffix()

​Destination.group()

​PortBinding

​binding.protocol

​PortBinding.tcp()

​PortBinding.udp()

​NetworkPolicy

​NetworkPolicy.none()

​NetworkPolicy.allow_all()

​NetworkPolicy.from_profiles()

​Types

​NetworkProfile

​NetworkDestination

​NetworkDestinationKind

​DnsConfig

​TlsConfig

​ScopedUpstreamCACert

​ScopedVerifyUpstream

​NetworkRateLimiter

​RateLimiter

​TokenBucket

​Action

​Direction

​Protocol

​PortProtocol

​DestGroup

Network

network.tcp_accept_queue_size

network.nat64_prefixes

max_udp_connections

network.max_tcp_connections

network.http

Network.none()

Network.from_profiles()

Network.allow_all()

Rule

Rule order matters

Rule.allow()

Rule.deny()

Rule.allow_dns()

Rule.deny_dns()

Destination

Destination.any()

Destination.ip()

Destination.cidr()

Destination.domain()

Destination.domain_suffix()

Destination.group()

PortBinding

binding.protocol

PortBinding.tcp()

PortBinding.udp()

NetworkPolicy

NetworkPolicy.none()

NetworkPolicy.allow_all()

NetworkPolicy.from_profiles()

Types

NetworkProfile

NetworkDestination

NetworkDestinationKind

DnsConfig

TlsConfig

ScopedUpstreamCACert

ScopedVerifyUpstream

NetworkRateLimiter

RateLimiter

TokenBucket

Action

Direction

Protocol

PortProtocol

DestGroup