Network
Used by Sandbox.create(network=…)
Sandbox network configuration.network.policy
NetworkPolicy \| None
Default: None.
Concrete network policy
network.ports
Mapping[int, int] \| Sequence[PortBinding]
Default: {}.
Port mappings from host to guest. Mapping form binds TCP to 127.0.0.1; PortBinding can set an explicit bind address or UDP
network.deny_domains
tuple[str, ...]
Default: ().
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
network.deny_domain_suffixes
tuple[str, ...]
Default: ().
Deny egress to all subdomains of these suffixes. Adds deny DomainSuffix("...") rules; same enforcement layers as deny_domains
network.dns
DnsConfig \| None
Default: None.
DNS interception configuration
network.tls
TlsConfig \| None
Default: None.
TLS interception configuration
network.strict
bool
Default: 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.
network.ipv4_pool
str \| None
Default: None.
IPv4 pool used for per-sandbox /30 guest subnets. Defaults to 172.16.0.0/12
network.ipv6_pool
str \| None
Default: None.
IPv6 pool used for per-sandbox /64 guest prefixes. Defaults to fd42:6d73:62::/48
network.max_inbound_tcp_connections
int \| None · Default: None
Limit active inbound TCP connections across published ports; 0 means unlimited. None uses the runtime default: unlimited in 0.7.9+, or 256 in older versions. Local-only; unsupported overrides fail with an upgrade-required error. Pass by keyword: Network(max_inbound_tcp_connections=512). Restore accepts the same keyword.
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.
Queue behavior and host limits
Queue behavior and host limits
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:
restore_with_progress() accepts the same options; max_connections remains a deprecated TCP-only alias, and supplying both TCP names is an error.
network.rate_limiter
NetworkRateLimiter \| None
Default: None.
Ingress and egress rate limits
network.secret_violation_action
ViolationAction
Default: BLOCK_AND_LOG.
Sandbox-wide action when a secret placeholder reaches a disallowed host
network.http
HttpConfig | None · Default: None
Denial responses default to JSON 403 errors. Set HttpConfig(deny_response=False) to disable them. network_deny_message and secret_deny_message customize the respective messages. Requires a supporting local runtime. See HTTP denial responses.
Example
Example
Network.none()
Example
Example
exec and fs still work since they use the host-guest channel, not the network.
Returns
Network.from_profiles()
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.
Returns
Network.allow_all()
Returns
Rule
Used by NetworkPolicy(rules=…)
Frozen dataclass for a single network policy rule. Prefer theRule.allow() / Rule.deny() class methods over the positional constructor.
rule.action
Action
Default: —.
What to do when this rule matches
rule.direction
Direction
Default: EGRESS.
Which evaluator considers this rule. Direction.ANY matches in either direction
rule.destination
str \| NetworkDestination \| None
Default: 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
rule.protocol
Protocol \| None
Default: None.
Protocol filter
rule.port
int \| str \| None
Default: 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=...).
Rule order matters
The first matching rule wins, so a broad rule placed before a narrow one swallows it:Rule.allow()
Example
Example
Parameters
directionDirectionEGRESS.protocolProtocol | Noneportint | str | None443) or range (“8000-9000”).destinationstr | NetworkDestination | NoneReturns
Rule.deny()
allow().
Parameters
directionDirectionEGRESS.protocolProtocol | Noneportint | str | None8000-9000. Invalid values and reversed ranges raise ValueError; omit the filter to match any port.destinationstr | NetworkDestination | NoneReturns
Rule.allow_dns()
Example
Example
(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()
Returns
(udp_rule, tcp_rule) for DestGroup.HOST on port 53.Destination
Returns NetworkDestination · used by Rule.allow() / Rule.deny()
Factory for typedNetworkDestination values.
Destination.any()
Destination.ip()
/32 for IPv4 or /128 for IPv6.
Parameters
ipstrDestination.cidr()
Parameters
cidrstr“10.0.0.0/8”.Destination.domain()
ValueError.
Parameters
domainstrDestination.domain_suffix()
Parameters
suffixstr“.example.com”.Destination.group()
DestGroup address group.
Parameters
groupDestGroupPortBinding
Used by Network(ports=…)
Frozen dataclass for a published host-to-guest port with an optional host bind address. Prefer thePortBinding.tcp() / PortBinding.udp() class methods.
binding.host_port
int
Default: —.
Port on the host
binding.guest_port
int
Default: —.
Port inside the sandbox
binding.bind
str
Default: "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.
Network(ports=(...)). A plain dict[int, int] is also accepted for the common case, binding TCP to 127.0.0.1.
PortBinding.tcp()
Parameters
host_portintguest_portintbindstr127.0.0.1; use 0.0.0.0 for all IPv4 interfaces.Returns
PortBinding.udp()
Parameters
host_portintguest_portintbindstr127.0.0.1.Returns
NetworkPolicy
Used by Network(policy=…)
Ordered rules with per-direction defaults.policy.default_egress
Action
Default: DENY.
Action when no egress-applicable rule matches
policy.default_ingress
Action
Default: ALLOW.
Action when no ingress-applicable rule matches
policy.rules
tuple[Rule, ...]
Default: ().
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()
Returns
NetworkPolicy
NetworkPolicy.allow_all()
Returns
NetworkPolicy
NetworkPolicy.from_profiles()
Returns
NetworkPolicy
Types
NetworkProfile
NetworkDestination
Produced by Destination helpers
Frozen dataclass produced byDestination helpers.
NetworkDestinationKind
Returned in NetworkDestination.kind
Network destination variant.DnsConfig
Used by Network(dns=…)
Frozen dataclass for DNS interception settings. The value type ofNetwork.dns; import it from microsandbox.types.
TlsConfig
Used by Network(tls=…)
Frozen dataclass for TLS interception settings withinNetwork.
ScopedUpstreamCACert
Used by TlsConfig(scoped_upstream_ca_certs=…)
A CA bundle trusted only for upstream hosts matching a pattern.ScopedVerifyUpstream
Used by TlsConfig(scoped_verify_upstream=…)
A per-host override for upstream certificate verification.NetworkRateLimiter
Used by Network.rate_limiter
Groups local network limits by traffic direction. An omitted direction is unlimited.RateLimiter
Held by NetworkRateLimiter
Limits bandwidth and packet rate for one traffic direction.TokenBucket
Used by RateLimiter
Token-bucket configuration for one rate-limiter dimension.Action
Used by NetworkPolicy · Rule
Policy action.Direction
Used by Rule
String enum for traffic direction.Protocol
Used by Rule
String enum for network protocols in policy rules.PortProtocol
Used by PortBinding
String enum for port-level protocol selection.DestGroup
Used by Destination.group()
String enum for well-known destination groups used inDestination.group() or string-shorthand Rule.destination.