--- title: Networking description: Rust SDK - Network API reference --- Configure sandbox networking. See [Networking](/networking/overview) for usage and policy concepts. ## NetworkPolicy

Built by NetworkPolicy::builder() · used by policy()

Ordered rules with per-direction defaults. #### NetworkPolicy::default_egress [`Action`](#action) Action when no egress-applicable rule matches #### NetworkPolicy::default_ingress [`Action`](#action) Action when no ingress-applicable rule matches #### NetworkPolicy::rules `Vec<`[`Rule`](#rule)`>` Ordered rules; first match wins per direction #### NetworkPolicy::builder() ```rust fn builder() -> NetworkPolicyBuilder ``` ```rust use microsandbox::NetworkPolicy; let policy = NetworkPolicy::builder() .default_deny() .egress(|e| e.tcp().port(443).allow_public().allow_private()) .build()?; ``` Start the fluent [`NetworkPolicyBuilder`](#networkpolicybuilder). The primary construction path: string inputs (`.ip`, `.cidr`, `.domain`, `.domain_suffix`) are stored raw and parsed at [`build()`](#build), so the chain stays clean and the first parse or validation failure surfaces as [`BuildError`](#builderror).

Returns

NetworkPolicyBuilder
Empty builder.
#### NetworkPolicy::none() ```rust fn none() -> NetworkPolicy ``` No network access: deny everything in both directions, no rules. This is the policy set by [`SandboxBuilder::disable_network()`](/sdk/rust/sandbox#disable_network). #### NetworkPolicy::allow_all() ```rust fn allow_all() -> NetworkPolicy ``` Unrestricted network access: allow everything in both directions, no rules. #### NetworkPolicy::from_profiles() ```rust fn from_profiles>(profiles: I) -> NetworkPolicy ``` Build a deny-by-default policy from composable [`NetworkProfile`](#networkprofile) values. Duplicate profiles are ignored, the generated rules use canonical `Public`, `Private`, `Host` order, and every non-empty profile set receives exactly one narrow gateway DNS rule. An empty profile set permits no egress and adds no DNS. Ingress defaults to allow, preserving published-port behavior. ```rust use microsandbox::{NetworkPolicy, NetworkProfile}; let policy = NetworkPolicy::from_profiles([ NetworkProfile::Public, NetworkProfile::Private, ]); ```

Instance methods

These methods consume `self` and return a modified policy, so they chain off a profile or a built policy. Each **prepends** its rules, so a later deny outranks a catch-all allow like `allow public` under first-match-wins. All return [`Result`](#domainname) because the names are parsed eagerly. #### policy.allow_domain() ```rust fn allow_domain>(self, name: S) -> Result ``` ```rust let policy = NetworkPolicy::default().allow_domain("api.openai.com")?; ``` Prepend a single allow-[`Domain`](#destination) egress rule. Single-name sugar over [`allow_domains()`](#policy-allow_domains). #### policy.deny_domain() ```rust fn deny_domain>(self, name: S) -> Result ``` Prepend a single deny-[`Domain`](#destination) egress rule. Single-name sugar over [`deny_domains()`](#policy-deny_domains). #### policy.allow_domains() ```rust fn allow_domains(self, names: I) -> Result where I: IntoIterator, S: AsRef, ``` ```rust let policy = NetworkPolicy::default() .allow_domains(["pypi.org", "files.pythonhosted.org"])?; ``` Prepend one allow-[`Domain`](#destination) egress rule per name.

Parameters

namesIntoIterator<Item = AsRef<str>>
Exact domain names.
#### policy.deny_domains() ```rust fn deny_domains(self, names: I) -> Result where I: IntoIterator, S: AsRef, ``` ```rust let policy = NetworkPolicy::allow_all() .deny_domains(["evil.com", "tracker.example"])?; ``` Prepend one deny-[`Domain`](#destination) egress rule per name. Prepending lets the denies outrank catch-all allows. #### policy.allow_domain_suffix() ```rust fn allow_domain_suffix>(self, suffix: S) -> Result ``` Prepend a single allow-[`DomainSuffix`](#destination) egress rule. Single-suffix sugar over [`allow_domain_suffixes()`](#policy-allow_domain_suffixes). #### policy.deny_domain_suffix() ```rust fn deny_domain_suffix>(self, suffix: S) -> Result ``` Prepend a single deny-[`DomainSuffix`](#destination) egress rule. Single-suffix sugar over [`deny_domain_suffixes()`](#policy-deny_domain_suffixes). #### policy.allow_domain_suffixes() ```rust fn allow_domain_suffixes(self, suffixes: I) -> Result where I: IntoIterator, S: AsRef, ``` Prepend one allow-[`DomainSuffix`](#destination) egress rule per suffix. Suffixes match the apex domain and every subdomain (label-aligned). #### policy.deny_domain_suffixes() ```rust fn deny_domain_suffixes(self, suffixes: I) -> Result where I: IntoIterator, S: AsRef, ``` ```rust let policy = NetworkPolicy::allow_all() .deny_domain_suffixes([".ads.example", ".doubleclick.net"])?; ``` Prepend one deny-[`DomainSuffix`](#destination) egress rule per suffix. ## NetworkPolicyBuilder Fluent builder for [`NetworkPolicy`](#networkpolicy). #### policy.default_deny() ```rust fn default_deny(self) -> Self ``` Set both `default_egress` and `default_ingress` to [`Deny`](#action). #### policy.default_allow() ```rust fn default_allow(self) -> Self ``` Set both `default_egress` and `default_ingress` to [`Allow`](#action). #### policy.default_egress() ```rust fn default_egress(self, action: Action) -> Self ``` Per-direction override for the egress default action.

Parameters

actionAction
Default action for egress.
#### policy.default_ingress() ```rust fn default_ingress(self, action: Action) -> Self ``` Per-direction override for the ingress default action.

Parameters

actionAction
Default action for ingress.
#### policy.egress() ```rust fn egress(self, f: F) -> Self where F: for<'a> FnOnce(&'a mut RuleBuilder) -> &'a mut RuleBuilder ``` ```rust NetworkPolicy::builder() .default_deny() .egress(|e| e.tcp().port(443).allow_public()) .build()?; ``` Sugar for [`rule()`](#rule) with direction pre-set to [`Egress`](#direction). #### policy.ingress() ```rust fn ingress(self, f: F) -> Self where F: for<'a> FnOnce(&'a mut RuleBuilder) -> &'a mut RuleBuilder ``` Sugar for [`rule()`](#rule) with direction pre-set to [`Ingress`](#direction). #### policy.any() ```rust fn any(self, f: F) -> Self where F: for<'a> FnOnce(&'a mut RuleBuilder) -> &'a mut RuleBuilder ``` Sugar for [`rule()`](#rule) with direction pre-set to [`Any`](#direction). Rules committed inside apply in both directions. #### policy.rule() ```rust fn rule(self, f: F) -> Self where F: for<'a> FnOnce(&'a mut RuleBuilder) -> &'a mut RuleBuilder ``` ```rust NetworkPolicy::builder() .rule(|r| r.egress().tcp().port(443).allow().domain("api.example.com")) .build()?; ``` Open a multi-rule batch closure. Direction must be set inside via [`.egress()`](#rb-egress), [`.ingress()`](#rb-ingress), or [`.any()`](#rb-any) before any rule-adder, otherwise [`build()`](#build) returns [`BuildError::DirectionNotSet`](#builderror). #### policy.build() ```rust fn build(self) -> Result ``` Consume the builder and produce a [`NetworkPolicy`](#networkpolicy). Lazy-parses every `.ip()` / `.cidr()` / `.domain()` / `.domain_suffix()` input, validates the direction-set and ICMP-egress-only invariants, and emits a `tracing::warn!` for each shadowed rule pair (a rule fully covered by an earlier one in the same direction; only `Ip` / `Cidr` / `Group` destinations are checked). Builds still succeed when a shadow is detected. Returns the first [`BuildError`](#builderror) encountered.

Returns

Validated policy.
## RuleBuilder Builder for one policy-rule batch. #### rule.egress() ```rust fn egress(&mut self) -> &mut Self ``` Set direction to [`Egress`](#direction) for subsequent rule-adders. Last-write-wins. #### rule.ingress() ```rust fn ingress(&mut self) -> &mut Self ``` Set direction to [`Ingress`](#direction) for subsequent rule-adders. Last-write-wins. #### rule.any() ```rust fn any(&mut self) -> &mut Self ``` Set direction to [`Any`](#direction) for subsequent rule-adders. Rules committed after this apply in both directions. Last-write-wins. #### rule.tcp() ```rust fn tcp(&mut self) -> &mut Self ``` Add [`Tcp`](#protocol) to the protocols set. #### rule.udp() ```rust fn udp(&mut self) -> &mut Self ``` Add [`Udp`](#protocol) to the protocols set. #### rule.icmpv4() ```rust fn icmpv4(&mut self) -> &mut Self ``` Add [`Icmpv4`](#protocol) to the protocols set. Egress-only: an ICMP protocol on an `Ingress` or `Any` rule fails build with [`BuildError::IngressDoesNotSupportIcmp`](#builderror). #### rule.icmpv6() ```rust fn icmpv6(&mut self) -> &mut Self ``` Add [`Icmpv6`](#protocol) to the protocols set. Egress-only; same rule as [`icmpv4()`](#icmpv4). #### rule.port() ```rust fn port(&mut self, port: u16) -> &mut Self ``` Add a single port to the ports set. Always guest-side (egress destination port / ingress listening port).

Parameters

portu16
Port number.
#### rule.port_range() ```rust fn port_range(&mut self, lo: u16, hi: u16) -> &mut Self ``` Add an inclusive port range.

Parameters

lou16
Lower bound (inclusive).
hiu16
Upper bound (inclusive). lo > hi records BuildError::InvalidPortRange.
#### rule.ports() ```rust fn ports>(&mut self, ports: I) -> &mut Self ``` Add multiple single ports. Equivalent to calling [`port()`](#port-1) once per element. #### rule.allow_public() ```rust fn allow_public(&mut self) -> &mut Self ``` Commit an allow rule for the [`Public`](#destinationgroup) group: every IP not in another named category. A matching [`deny_public()`](#deny_public) exists for each `allow_*` group adder below. #### rule.allow_private() ```rust fn allow_private(&mut self) -> &mut Self ``` Allow the [`Private`](#destinationgroup) group (RFC1918 + ULA + CGN). #### rule.allow_loopback() ```rust fn allow_loopback(&mut self) -> &mut Self ``` Allow the [`Loopback`](#destinationgroup) group (`127.0.0.0/8`, `::1`): the **guest's own** loopback, not the host. To reach a service on the host's localhost use [`allow_host()`](#allow_host) instead. See the [loopback-vs-host trap](/networking/overview#loopback-vs-host-a-common-trap). #### rule.allow_link_local() ```rust fn allow_link_local(&mut self) -> &mut Self ``` Allow the [`LinkLocal`](#destinationgroup) group (`169.254.0.0/16`, `fe80::/10`). Excludes the metadata IP `169.254.169.254`. #### rule.allow_meta() ```rust fn allow_meta(&mut self) -> &mut Self ``` Allow the [`Metadata`](#destinationgroup) group (`169.254.169.254`). **Dangerous on cloud hosts**: exposes IAM credentials. #### rule.allow_multicast() ```rust fn allow_multicast(&mut self) -> &mut Self ``` Allow the [`Multicast`](#destinationgroup) group (`224.0.0.0/4`, `ff00::/8`). #### rule.allow_host() ```rust fn allow_host(&mut self) -> &mut Self ``` Allow the [`Host`](#destinationgroup) group: per-sandbox gateway IPs that back `host.microsandbox.internal`. This is the right shortcut for "let the sandbox reach my host's localhost", not [`allow_loopback()`](#allow_loopback). #### rule.deny_public() ```rust fn deny_public(&mut self) -> &mut Self ``` Deny the [`Public`](#destinationgroup) group. Per-group `deny_*` adders mirror the `allow_*` set: `deny_private()`, `deny_loopback()`, `deny_link_local()`, `deny_meta()`, `deny_multicast()`, and `deny_host()`. #### rule.allow_local() ```rust fn allow_local(&mut self) -> &mut Self ``` Commit **three** allow rules atomically: [`Loopback`](#destinationgroup) + `LinkLocal` + `Host`. Each uses the closure's current state. `Metadata` is intentionally excluded; opt in via [`allow_meta()`](#allow_meta) separately. #### rule.deny_local() ```rust fn deny_local(&mut self) -> &mut Self ``` Commit three deny rules atomically: `Loopback` + `LinkLocal` + `Host`. `Metadata` is intentionally excluded. #### rule.allow_domains() ```rust fn allow_domains(&mut self, names: I) -> &mut Self where I: IntoIterator, S: Into ``` ```rust NetworkPolicy::builder() .default_allow() .egress(|e| e .deny_domains(["evil.com", "tracker.example"]) .deny_domain_suffixes([".ads.example", ".doubleclick.net"])) .build()?; ``` Add one allow-[`Domain`](#destination) rule per name, inheriting the closure's current direction / protocol / port state. Lazy-parse: invalid names surface as [`BuildError::InvalidDomain`](#builderror) from [`build()`](#build). #### rule.deny_domains() ```rust fn deny_domains(&mut self, names: I) -> &mut Self where I: IntoIterator, S: Into ``` Add one deny-[`Domain`](#destination) rule per name. #### rule.allow_domain_suffixes() ```rust fn allow_domain_suffixes(&mut self, suffixes: I) -> &mut Self where I: IntoIterator, S: Into ``` Add one allow-[`DomainSuffix`](#destination) rule per suffix. #### rule.deny_domain_suffixes() ```rust fn deny_domain_suffixes(&mut self, suffixes: I) -> &mut Self where I: IntoIterator, S: Into ``` Add one deny-[`DomainSuffix`](#destination) rule per suffix. #### rule.allow() ```rust fn allow(&mut self) -> RuleDestinationBuilder<'_> ``` ```rust NetworkPolicy::builder() .egress(|e| e.tcp().port(443).allow().domain("api.example.com")) .any(|a| a.deny().cidr("198.51.100.0/24")) .build()?; ``` Begin an explicit-destination rule with action [`Allow`](#action). The returned [`RuleDestinationBuilder`](#ruledestinationbuilder) requires exactly one destination call to commit; dropping it without one adds no rule. #### rule.deny() ```rust fn deny(&mut self) -> RuleDestinationBuilder<'_> ``` Begin an explicit-destination rule with action [`Deny`](#action). ## RuleDestinationBuilder Builder for a rule destination. #### destination.ip() ```rust fn ip(self, ip: impl Into) -> &'a mut RuleBuilder ``` Commit with [`Destination::Cidr`](#destination) of the IP as `/32` (v4) or `/128` (v6). The string is parsed at [`build()`](#build); invalid values surface as [`BuildError::InvalidIp`](#builderror). #### destination.cidr() ```rust fn cidr(self, cidr: impl Into) -> &'a mut RuleBuilder ``` Commit with [`Destination::Cidr`](#destination). Invalid values surface as [`BuildError::InvalidCidr`](#builderror). #### destination.domain() ```rust fn domain(self, domain: impl Into) -> &'a mut RuleBuilder ``` Commit with [`Destination::Domain`](#destination). Matches only when a cached hostname for the remote IP equals this name (after canonicalization). #### destination.domain_suffix() ```rust fn domain_suffix(self, suffix: impl Into) -> &'a mut RuleBuilder ``` Commit with [`Destination::DomainSuffix`](#destination). Matches the apex domain itself and any subdomain. A single-label suffix (e.g. `com`) is rejected at build as [`BuildError::InvalidDomain`](#builderror). #### destination.group() ```rust fn group(self, group: DestinationGroup) -> &'a mut RuleBuilder ``` Commit with [`Destination::Group`](#destination) for callers who already hold a [`DestinationGroup`](#destinationgroup) value. #### destination.any() ```rust fn any(self) -> &'a mut RuleBuilder ``` Commit with [`Destination::Any`](#destination): matches every remote. ## NetworkBuilder Builder for the sandbox's network stack, used in [`SandboxBuilder::network(|n| n...)`](/sdk/rust/sandbox#network). Every setter returns `Self`, so calls chain. Errors accumulated by nested builders cascade up: the outermost `SandboxBuilder::build()` surfaces them as [`MicrosandboxError::NetworkBuilder(BuildError)`](#builderror). #### network.policy() ```rust fn policy(self, policy: NetworkPolicy) -> Self ``` ```rust .network(|n| n.policy(NetworkPolicy::builder().default_deny().build()?)) ``` Set the network access policy. Pass a profile-composed or builder-constructed [`NetworkPolicy`](#networkpolicy).

Parameters

Access policy.
#### network.port() Local-only ```rust fn port(self, host_port: u16, guest_port: u16) -> Self ``` Publish a TCP port from the sandbox to the host. The default host bind address is `127.0.0.1`. Equivalent to [`SandboxBuilder::port()`](/sdk/rust/sandbox#port).

Parameters

host_portu16
Port on the host.
guest_portu16
Port inside the sandbox.
#### network.port_udp() Local-only ```rust fn port_udp(self, host_port: u16, guest_port: u16) -> Self ``` Publish a UDP port. The default host bind address is `127.0.0.1`. #### network.port_bind() Local-only ```rust fn port_bind(self, host_bind: IpAddr, host_port: u16, guest_port: u16) -> Self ``` Publish a TCP port on a specific host bind address, such as `0.0.0.0`.

Parameters

host_bindIpAddr
Host bind address.
host_portu16
Port on the host.
guest_portu16
Port inside the sandbox.
#### network.port_udp_bind() Local-only ```rust fn port_udp_bind(self, host_bind: IpAddr, host_port: u16, guest_port: u16) -> Self ``` Publish a UDP port on a specific host bind address. #### network.dns() Local-only ```rust fn dns(self, f: impl FnOnce(DnsBuilder) -> DnsBuilder) -> Self ``` ```rust use microsandbox_network::dns::Nameserver; .network(|n| n .dns(|d| d .nameservers(["1.1.1.1".parse::()?]) .query_timeout_ms(3000))) ``` Configure DNS interception. See [`DnsBuilder`](#dnsbuilder). #### network.tls() Local-only ```rust fn tls(self, f: impl FnOnce(TlsBuilder) -> TlsBuilder) -> Self ``` Configure TLS interception. See [`TlsBuilder`](#tlsbuilder). #### network.trust_host_cas() Local-only ```rust fn trust_host_cas(self, enabled: bool) -> Self ``` Whether to ship the host's trusted root CAs into the guest at boot. Default: `false`. Opt in when egress HTTPS inside the sandbox needs to work behind corporate MITM proxies (Cloudflare Warp Zero Trust, Zscaler, Netskope, etc.): those proxies install a gateway CA on the host that's unknown to the guest's stock Mozilla bundle. #### network.max_connections() ```rust fn max_connections(self, max: usize) -> Self ``` Limit the maximum number of concurrent network connections from the sandbox. Default: `256`.

Parameters

maxusize
Maximum concurrent connections.
#### network.rate_limiter() ```rust fn rate_limiter(self, f: impl FnOnce(NetworkRateLimiterBuilder) -> NetworkRateLimiterBuilder) -> Self ``` ```rust use std::time::Duration; use microsandbox::size::SizeExt; .network(|n| n.rate_limiter(|r| r .egress(|r| r .bandwidth(1.mib(), Duration::from_secs(1)) .bandwidth_burst(512.kib()) .ops(1_000, Duration::from_secs(1))) .ingress(|r| r.ops(1_000, Duration::from_secs(1))))) ``` Configure local network rate limits. Egress and ingress are independently optional; an omitted direction is unlimited. The limit applies on the next sandbox start. Cloud network configuration does not expose rate limits. #### network.ipv4_pool() Local-only ```rust fn ipv4_pool(self, pool: Ipv4Network) -> Self ``` Set the IPv4 pool used to derive per-sandbox `/30` guest subnets. Defaults to `172.16.0.0/12`. A pool with a prefix longer than `/30` records [`BuildError::InvalidIpv4Pool`](#builderror).

Parameters

poolIpv4Network
IPv4 pool, prefix /30 or shorter.
#### network.ipv6_pool() Local-only ```rust fn ipv6_pool(self, pool: Ipv6Network) -> Self ``` Set the IPv6 pool used to derive per-sandbox `/64` guest prefixes. Defaults to `fd42:6d73:62::/48`. A pool with a prefix longer than `/64` records [`BuildError::InvalidIpv6Pool`](#builderror). #### network.interface() Local-only ```rust fn interface(self, overrides: InterfaceOverrides) -> Self ``` Override the guest interface settings wholesale: MAC, MTU, IPv4/IPv6 addresses, and the derivation pools. A low-level escape hatch. For the common case of changing only the address pools, prefer [`ipv4_pool()`](#ipv4_pool) and [`ipv6_pool()`](#ipv6_pool), which validate the prefix. Unset fields fall back to values derived deterministically from the sandbox slot. See [`InterfaceOverrides`](#interfaceoverrides).

Parameters

Guest interface overrides.
#### network.enabled() ```rust fn enabled(self, enabled: bool) -> Self ``` Enable or disable networking. Default: `true`. To fully turn networking off, prefer [`SandboxBuilder::disable_network()`](/sdk/rust/sandbox#disable_network), which also sets the policy to [`NetworkPolicy::none()`](#networkpolicynone). #### network.on_secret_violation() ```rust fn on_secret_violation( self, f: impl FnOnce(ViolationActionBuilder) -> ViolationActionBuilder, ) -> Self ``` ```rust .network(|n| n.on_secret_violation(|v| v .block_and_log() .passthrough_host("api.anthropic.com") .passthrough_host_pattern("*.example.com"))) ``` Set the sandbox-wide action taken when a secret placeholder is detected in traffic to a host not in the secret's allow list. See [`ViolationActionBuilder`](#violationactionbuilder). Passthrough hosts receive the placeholder unchanged. They do **not** receive real secret values. #### network.secret() ```rust fn secret(self, f: impl FnOnce(SecretBuilder) -> SecretBuilder) -> Self ``` Add a secret via a closure builder. Mirrors [`SandboxBuilder::secret()`](/sdk/rust/sandbox#secret). See [`SecretBuilder`](/sdk/rust/secrets#secretbuilder) for the full API. A companion `secret_env(env_var, value, placeholder, allowed_host)` shorthand and `secret_entry(SecretEntry)` are also available on `NetworkBuilder`.

Parameters

Configure the secret.
## DnsBuilder Builder for DNS interception, used in [`NetworkBuilder::dns(|d| d...)`](#dns). Owns rebind protection, nameserver pinning, and the per-query timeout. Every setter returns `Self`. #### dns.nameservers() Local-only ```rust fn nameservers(self, nameservers: I) -> Self where I: IntoIterator, I::Item: Into ``` Set the upstream nameservers to forward DNS queries to. Replaces any previously-set nameservers. When empty, the interceptor falls back to the host's `/etc/resolv.conf` (or, on macOS, the SystemConfiguration dynamic store). Each element converts into [`Nameserver`](#nameserver): a `SocketAddr`, an `IpAddr`, or a parsed string via `"dns.google:53".parse::()?`.

Parameters

nameserversIntoIterator<Item = Into<Nameserver>>
Upstream resolvers.
#### dns.query_timeout_ms() ```rust fn query_timeout_ms(self, ms: u64) -> Self ``` Set the per-DNS-query timeout in milliseconds. Default: `5000`. #### dns.rebind_protection() ```rust fn rebind_protection(self, enabled: bool) -> Self ``` When enabled, DNS responses that resolve to private IP addresses are blocked, preventing DNS rebinding attacks. Default: `true`. ## TlsBuilder Builder for TLS interception, used in [`NetworkBuilder::tls(|t| t...)`](#tls). Creating it enables interception. Every setter returns `Self`. #### tls.bypass() ```rust fn bypass(self, pattern: impl Into) -> Self ``` Skip TLS interception for hosts matching this glob (e.g. `"*.internal.corp"`). Use for domains with certificate pinning. Can be called multiple times.

Parameters

patternimpl Into<String>
Host glob. Supports exact match and *.suffix wildcards.
#### tls.intercepted_ports() Local-only ```rust fn intercepted_ports(self, ports: Vec) -> Self ``` TCP ports where TLS interception is active. Default: `[443]`. #### tls.verify_upstream() ```rust fn verify_upstream(self, verify: bool) -> Self ``` Whether the proxy verifies upstream server certificates. Default: `true`. Set to `false` only for self-signed servers. #### tls.block_quic() ```rust fn block_quic(self, block: bool) -> Self ``` Block QUIC/HTTP3 on intercepted ports, forcing TCP/TLS fallback. Default: `true`. #### tls.intercept_ca_cert() Local-only ```rust fn intercept_ca_cert(self, path: impl Into) -> Self ``` PEM file used as the intercepting CA's certificate. Pair with [`intercept_ca_key()`](#intercept_ca_key) to provide a stable CA across sandbox restarts. If unset, a CA is auto-generated and persisted. #### tls.intercept_ca_key() Local-only ```rust fn intercept_ca_key(self, path: impl Into) -> Self ``` PEM file used as the intercepting CA's private key. #### tls.upstream_ca_cert() ```rust fn upstream_ca_cert(self, path: impl Into) -> Self ``` PEM file with extra root CAs the proxy should trust when verifying every upstream server. Useful for self-signed or private upstream CAs. Can be called multiple times. #### tls.upstream_ca_cert_for() ```rust fn upstream_ca_cert_for( self, pattern: impl Into, path: impl Into, ) -> Self ``` PEM file with extra root CAs the proxy should trust only when the upstream SNI matches `pattern`. Pattern syntax matches [`bypass()`](#bypass): exact hosts and `*.suffix` wildcards are supported. #### tls.verify_upstream_for() ```rust fn verify_upstream_for( self, pattern: impl Into, verify: bool, ) -> Self ``` Whether the proxy verifies upstream server certificates only when the upstream SNI matches `pattern`. Pattern syntax matches [`bypass()`](#bypass): exact hosts and `*.suffix` wildcards are supported. Setting `verify` to `false` is the proxy-side equivalent of `curl -k` for matching hosts; TLS interception still runs. ## ViolationActionBuilder Builder for secret-violation behavior. #### violation.block() ```rust fn block(self) -> Self ``` Block the request silently. #### violation.block_and_log() ```rust fn block_and_log(self) -> Self ``` Block the request and emit a warning log on the host. This is the [`ViolationAction`](#violationaction) default. #### violation.block_and_terminate() ```rust fn block_and_terminate(self) -> Self ``` Block the request and terminate the entire sandbox. #### violation.passthrough_host() ```rust fn passthrough_host(self, host: impl Into) -> Self ``` Allow an exact host to receive secret placeholders unchanged (no substitution).

Parameters

hostimpl Into<String>
Exact host.
#### violation.passthrough_host_pattern() ```rust fn passthrough_host_pattern(self, pattern: impl Into) -> Self ``` Allow hosts matching a wildcard pattern (e.g. `*.example.com`) to receive placeholders unchanged. #### violation.passthrough_all_hosts() ```rust fn passthrough_all_hosts(self, i_understand_the_risk: bool) -> Self ``` Allow **any** host to receive placeholders unchanged. Takes effect only when `i_understand_the_risk` is `true`.

Parameters

i_understand_the_riskbool
Must be true to take effect.
## NetworkRateLimiterBuilder Groups local rate limits by traffic direction. Supplied to [`NetworkBuilder::rate_limiter()`](#rate_limiter). #### .egress() ```rust fn egress(self, f: impl FnOnce(RateLimiterBuilder) -> RateLimiterBuilder) -> Self ``` Configure the guest-to-runtime direction. #### .ingress() ```rust fn ingress(self, f: impl FnOnce(RateLimiterBuilder) -> RateLimiterBuilder) -> Self ``` Configure the runtime-to-guest direction. ## RateLimiterBuilder Builder for one direction's rate limiter, supplied to [`NetworkRateLimiterBuilder::egress()`](#egress) or [`ingress()`](#ingress). A limiter caps bandwidth (bytes) and packet rate (frames) independently; leaving a bucket unset leaves that dimension unlimited. Buckets start full plus their one-time burst and refill continuously. Every setter returns `Self`. Validation runs at `NetworkBuilder::build()`: a limiter with neither bucket, a zero bucket size or refill interval, a burst without its bucket, or a refill interval that does not fit in u64 milliseconds surfaces as [`BuildError`](#builderror). #### .bandwidth() ```rust fn bandwidth(self, size: impl Into, refill_time: Duration) -> Self ``` Cap bandwidth at `size` bytes per `refill_time`. Size accepts a bare `u64` byte count or the unit helpers from `microsandbox::size::SizeExt` (`1.mib()`, `512.kib()`).

Parameters

sizeimpl Into<Bytes>
Bucket capacity in bytes.
refill_timeDuration
Time to refill the full bucket.
#### .bandwidth_burst() ```rust fn bandwidth_burst(self, burst: impl Into) -> Self ``` Grant a one-time startup burst of extra bytes on top of the bandwidth bucket. The burst is spent before the regular budget and never refills. Requires [`bandwidth()`](#bandwidth). #### .ops() ```rust fn ops(self, count: u64, refill_time: Duration) -> Self ``` Cap packet rate at `count` frames per `refill_time`. #### .ops_burst() ```rust fn ops_burst(self, count: u64) -> Self ``` Grant a one-time startup burst of extra frames on top of the ops bucket. Requires [`ops()`](#ops). --- ## Rule

Held by NetworkPolicy

A single policy rule. The `destination` interpretation is direction-dependent: egress destination, or ingress peer/source. `ports` is always the guest-side port (egress destination port / ingress listening port). #### Rule::direction [`Direction`](#direction) Which evaluator considers this rule #### Rule::destination [`Destination`](#destination) Target filter #### Rule::protocols `Vec<`[`Protocol`](#protocol)`>` Set semantics; empty = any protocol #### Rule::ports `Vec<`[`PortRange`](#portrange)`>` Set semantics; empty = any port #### Rule::action [`Action`](#action) What to do on match Convenience constructors build any-protocol, any-port rules: #### Rule::allow_egress() ```rust Rule::allow_egress(destination) ``` Allow rule, direction `Egress` #### Rule::deny_egress() ```rust Rule::deny_egress(destination) ``` Deny rule, direction `Egress` #### Rule::allow_ingress() ```rust Rule::allow_ingress(destination) ``` Allow rule, direction `Ingress` #### Rule::deny_ingress() ```rust Rule::deny_ingress(destination) ``` Deny rule, direction `Ingress` #### Rule::allow_any() ```rust Rule::allow_any(destination) ``` Allow rule, direction `Any` #### Rule::deny_any() ```rust Rule::deny_any(destination) ``` Deny rule, direction `Any` #### Rule::allow_dns() ```rust Rule::allow_dns() ``` Allow plain DNS (UDP/53 + TCP/53) to the gateway forwarder (`Group::Host`); the one-liner for opening DNS under deny-by-default. See [DNS as egress](/networking/dns#dns-as-egress) #### Rule::deny_dns() ```rust Rule::deny_dns() ``` Deny plain DNS (UDP/53 + TCP/53) to the gateway forwarder; place before profile-generated rules to override automatic DNS ## PortRange

Held by Rule · added by port() · port_range()

An inclusive port range. #### PortRange::start `u16` Start port (inclusive) #### PortRange::end `u16` End port (inclusive) #### PortRange::single() ```rust PortRange::single(port) ``` Match a single port #### PortRange::range() ```rust PortRange::range(start, end) ``` Match an inclusive range #### PortRange::contains() ```rust contains(port) ``` Whether `port` falls within the range ## DomainName

Held by Destination::Domain / DomainSuffix

A validated, canonical DNS name. #### name.as_str() ```rust as_str() ``` Borrow the canonical string form #### name.try_into_suffix() ```rust try_into_suffix() ``` Validate for use as a `DomainSuffix`; single-label names (e.g. `com`) are rejected ## Types ### NetworkProfile Composable high-level access category accepted by [`NetworkPolicy::from_profiles()`](#networkpolicyfrom_profiles). | Variant | Access | |---------|--------| | `Public` | Public internet addresses | | `Private` | Private/LAN ranges (RFC 1918, RFC 4193 ULA, and CGN) | | `Host` | The sandbox host via its gateway addresses | ### Action

Used by Rule · NetworkPolicy · default_egress()

| Value | Wire format | Description | |-------|-------------|-------------| | `Allow` | `"allow"` | Permit the traffic | | `Deny` | `"deny"` | Drop the traffic silently | ### Direction

Used by Rule

| Value | Wire format | Description | |-------|-------------|-------------| | `Egress` | `"egress"` | Traffic leaving the sandbox | | `Ingress` | `"ingress"` | Traffic entering the sandbox (via published ports) | | `Any` | `"any"` | Rule applies in either direction | ### Destination

Held by Rule · committed by RuleDestinationBuilder

| Variant | Description | |---------|-------------| | `Any` | Match any address | | `Cidr(IpNetwork)` | Match a CIDR range (e.g. `10.0.0.0/8`); single IPs are stored as `/32` or `/128` | | `Domain(`[`DomainName`](#domainname)`)` | Match an exact domain (e.g. `example.com`) when a cached hostname for the remote IP equals it | | `DomainSuffix(`[`DomainName`](#domainname)`)` | Match the apex domain and every subdomain (e.g. `example.com` and `api.example.com`) | | `Group(`[`DestinationGroup`](#destinationgroup)`)` | Match a predefined address group | ### DestinationGroup

Held by Destination · committed by RuleBuilder group adders

Groups are disjoint with one carve-out: `Metadata` takes precedence over `LinkLocal` for `169.254.169.254`, and `Host` over `Private` when the gateway IPs sit in CGN/ULA ranges. | Value | Wire format | Matches | |-------|-------------|---------| | `Public` | `"public"` | Complement of the other categories: every address not in any other group | | `Loopback` | `"loopback"` | `127.0.0.0/8`, `::1` (the **guest's own** loopback, not the host) | | `Private` | `"private"` | RFC1918 (`10/8`, `172.16/12`, `192.168/16`) + CGN (`100.64/10`) + ULA (`fc00::/7`) | | `LinkLocal` | `"link_local"` | `169.254.0.0/16`, `fe80::/10` (excludes metadata) | | `Metadata` | `"metadata"` | Cloud metadata endpoint (`169.254.169.254`) | | `Multicast` | `"multicast"` | `224.0.0.0/4`, `ff00::/8` | | `Host` | `"host"` | Per-sandbox gateway IPs that back `host.microsandbox.internal` | ### Protocol

Held by Rule · set by RuleBuilder protocol setters

| Value | Wire format | |-------|-------------| | `Tcp` | `"tcp"` | | `Udp` | `"udp"` | | `Icmpv4` | `"icmpv4"` | | `Icmpv6` | `"icmpv6"` | ICMP protocols are egress-only. A rule with direction `Ingress` or `Any` carrying an ICMP protocol fails build with [`BuildError::IngressDoesNotSupportIcmp`](#builderror). ### Nameserver

Used by nameservers()

An upstream DNS server, either a literal address or a hostname resolved at interceptor startup via the host's OS resolver. Serializes as a single string. Construct via `From`, `From`, or `str::parse` (errors with `ParseNameserverError`). | Variant | Description | |---------|-------------| | `Addr(SocketAddr)` | Literal socket address, ready to use | | `Host { host: String, port: u16 }` | Hostname + port resolved at startup | Accepted parse forms: `1.1.1.1`, `1.1.1.1:5353`, `2606:4700:4700::1111`, `[2606:4700:4700::1111]:53`, `dns.google`, `dns.google:53`. A bare IP or hostname defaults to port `53`. ### InterfaceOverrides

Used by interface()

Per-sandbox guest interface overrides. Every field is optional; an omitted field is derived deterministically from the sandbox slot. Most callers only touch the pools via [`ipv4_pool()`](#ipv4_pool) / [`ipv6_pool()`](#ipv6_pool) rather than constructing this directly. | Field | Type | Description | |-------|------|-------------| | mac | `Option<[u8; 6]>` | Guest MAC address. Default: derived from slot | | mtu | `Option` | Interface MTU. Default: `1500` | | ipv4_address | `Option` | Guest IPv4 address. Default: derived from slot within `ipv4_pool` | | ipv4_pool | `Option` | IPv4 pool guest subnets are derived from. Default: `172.16.0.0/12` | | ipv6_address | `Option` | Guest IPv6 address. Default: derived from slot within `ipv6_pool` | | ipv6_pool | `Option` | IPv6 pool guest prefixes are derived from. Default: `fd42:6d73:62::/48` | ### NetworkRateLimiterConfig

Built by NetworkRateLimiterBuilder · used by rate_limiter()

Local network rate limits grouped by direction. An omitted direction is unlimited. | Field | Type | Description | |-------|------|-------------| | egress | `Option<`[`RateLimiterConfig`](#ratelimiterconfig)`>` | Guest-to-runtime limit | | ingress | `Option<`[`RateLimiterConfig`](#ratelimiterconfig)`>` | Runtime-to-guest limit | ### RateLimiterConfig

Built by RateLimiterBuilder · held by NetworkRateLimiterConfig

Rate limiter for one traffic direction. A missing bucket leaves that dimension unlimited. | Field | Type | Description | |-------|------|-------------| | bandwidth | `Option<`[`TokenBucketConfig`](#tokenbucketconfig)`>` | Byte budget; one token per byte of frame data | | ops | `Option<`[`TokenBucketConfig`](#tokenbucketconfig)`>` | Packet budget; one token per network frame | ### TokenBucketConfig

Held by RateLimiterConfig

One token bucket of a rate limiter. The bucket starts full and refills continuously at `size` tokens per `refill_time_ms`; the one-time burst is spent before the regular budget and never refills. | Field | Type | Description | |-------|------|-------------| | size | `u64` | Bucket capacity in tokens; must be greater than zero | | refill_time_ms | `u64` | Time to refill `size` tokens, in milliseconds; must be greater than zero | | one_time_burst | `u64` | Extra startup-only tokens. Default: `0` | ### BuildError

Returned by NetworkPolicyBuilder::build() · wrapped by NetworkBuilder

Errors surfaced by the builders' `build()` methods. The same enum covers [`NetworkPolicy::builder()`](#networkpolicybuilder), [`DnsBuilder`](#dnsbuilder), and [`NetworkBuilder`](#networkbuilder); the network and DNS builders accumulate lazily, so the first failure surfaces from the outermost `build()` in the chain. | Variant | Cause | |---------|-------| | `DirectionNotSet { rule_index }` | A rule was committed without `.egress() / .ingress() / .any()` | | `MissingDestination { rule_index }` | `.allow()` or `.deny()` was called but no destination method followed | | `InvalidIp { rule_index, raw }` | `.ip(&str)` got an unparseable value | | `InvalidCidr { rule_index, raw }` | `.cidr(&str)` got an unparseable value | | `InvalidIpv4Pool { raw }` | `ipv4_pool()` got a pool that can't hold a `/30` sandbox subnet | | `InvalidIpv6Pool { raw }` | `ipv6_pool()` got a pool that can't hold a `/64` sandbox prefix | | `InvalidDomain { rule_index, raw, source }` | `.domain` / `.domain_suffix` got a value that failed `DomainName` parse | | `InvalidPortRange { rule_index, lo, hi }` | `.port_range(lo, hi)` had `lo > hi` | | `IngressDoesNotSupportIcmp { rule_index }` | ICMP protocol on a non-egress rule | | `InvalidSecretConfig { source }` | A secret entry failed validation | | `InvalidRateLimitConfig { direction, source }` | A rate limiter had no buckets, a zero bucket size, or a zero refill interval | | `EmptyNetworkRateLimiter` | `rate_limiter()` configured neither egress nor ingress | | `RateLimitBurstWithoutBucket { direction, bucket }` | `bandwidth_burst()` / `ops_burst()` without the matching bucket | | `RateLimitRefillTooLong { direction, bucket }` | A refill interval that does not fit in u64 milliseconds | Inside `SandboxBuilder::build()`, `BuildError` is wrapped as `MicrosandboxError::NetworkBuilder(BuildError)`. ### ViolationAction

Built by ViolationActionBuilder · used by on_secret_violation()

Action taken when a secret placeholder is sent to a disallowed host. Also documented on the [Secrets](/sdk/rust/secrets#violationaction) page, where it pairs with [`SecretBuilder`](/sdk/rust/secrets#secretbuilder). | Value | Wire format | Description | |-------|-------------|-------------| | `Block` | `"block"` | Silently drop the request | | `BlockAndLog` | `"block-and-log"` | Drop the request and emit a warning log (the default) | | `BlockAndTerminate` | `"block-and-terminate"` | Drop the request, log an error, and shut down the sandbox | | `Passthrough(Vec<`[`HostPattern`](/sdk/rust/secrets#hostpattern)`>)` | `"passthrough"` | Forward matching hosts with the placeholder unchanged; non-matching hosts use the default action |