--- title: Networking description: TypeScript SDK - Network API reference --- Configure a sandbox's network stack: a first-match-wins egress/ingress policy, published ports, DNS interception, TLS interception, and secret-violation handling. See [Networking](/networking/overview) for the conceptual overview and [TLS Interception](/networking/tls) for proxy details.

Factory · NetworkPolicy5

NetworkPolicy.builder()start the fluent builder NetworkPolicy.none()deny everything NetworkPolicy.allowAll()allow everything NetworkPolicy.publicOnly()public internet only (default) NetworkPolicy.nonLocal()public + private, no local

Factory · Rule / Destination / PortRange14

Rule.allowEgress()allow rule, egress Rule.denyEgress()deny rule, egress Rule.allowIngress()allow rule, ingress Rule.denyIngress()deny rule, ingress Rule.allowAny()allow rule, both directions Rule.denyAny()deny rule, both directions Rule.allowDns()open plain DNS to gateway Destination.any()match any destination Destination.cidr()match an IP range Destination.domain()match an exact domain Destination.domainSuffix()match apex + subdomains Destination.group()match an address group PortRange.single()a single port PortRange.range()an inclusive port range

Builder · NetworkBuilder18

.policy() .port() .portUdp() .portBind() .portUdpBind() .dns() .tls() .trustHostCAs() .maxConnections() .ipv4Pool() .ipv6Pool() .interface() .enabled() .onSecretViolation() .secret() .secretEnv() .secretEnvSimple() .build()

Builder · NetworkPolicyBuilder9

.defaultDeny() .defaultAllow() .defaultEgress() .defaultIngress() .egress() .ingress() .any() .rule() .build()

Builder · RuleBuilder36

.egress() .ingress() .any() .tcp() .udp() .port() .allowPublic() .allowPrivate() .allowHost() .allowLocal() .allowDomains() .allow() .deny() + 23 more in the RuleBuilder section

Builder · RuleDestinationBuilder6

.ip() .cidr() .domain() .domainSuffix() .group() .any()

Builder · DnsBuilder · TlsBuilder · ViolationActionBuilder18

.nameservers() .queryTimeoutMs() .rebindProtection() .bypass() .interceptedPorts() .verifyUpstream() .blockQuic() .interceptCaCert() .interceptCaKey() .upstreamCaCert() .upstreamCaCertFor() .verifyUpstreamFor() .block() .blockAndLog() .blockAndTerminate() .passthroughHost() .passthroughHostPattern() .passthroughAllHosts()

Types

NetworkConfig NetworkPolicy Rule Action Direction Destination DestinationGroup Protocol PortRange PublishedPort DnsConfig TlsConfig ViolationAction

Typical flow

```typescript import { NetworkPolicy, Sandbox } from "microsandbox"; const policy = NetworkPolicy.builder() // 1. compose a policy .defaultDeny() .egress((e) => e.tcp().port(443).allowPublic()) .rule((r) => r.any().deny((d) => d.ip("198.51.100.5"))) .build(); const sb = await Sandbox.builder("api") .image("python") .network((n) => n // 2. wire it into the sandbox .policy(policy) .port(8080, 80) .dns((d) => d.rebindProtection(true)), ) .create(); ``` The default policy denies egress except for an implicit allow-public rule (plus DNS), and allows ingress with no rules. See the [defaults rationale](/networking/overview#defaults) for the asymmetry. `NetworkPolicy`, `Rule`, `Destination`, and `PortRange` each merge a value-type interface with a factory namespace under one name, all re-exported from `microsandbox`. ## NetworkPolicy A [`NetworkPolicy`](#networkpolicy-2) is an ordered rule list plus two per-direction defaults, evaluated first-match-wins. The presets below construct common shapes directly; for anything custom, start from [`builder()`](#networkpolicybuilder) or write a literal and pass it to [`NetworkBuilder.policy()`](#policy). ```typescript import { NetworkPolicy, Rule, Destination } from "microsandbox"; // Custom policy literal const custom: NetworkPolicy = { defaultEgress: "deny", defaultIngress: "allow", rules: [ Rule.allowEgress(Destination.domain("api.example.com")), Rule.denyEgress(Destination.group("metadata")), ], }; // Or via the builder const built = NetworkPolicy.builder() .defaultDeny() .egress((e) => e.tcp().port(443).allowPublic()) .build(); ``` ### Rule order matters The first matching rule wins, so a broad rule placed before a narrow one swallows it: ```typescript const policy: NetworkPolicy = { defaultEgress: "deny", defaultIngress: "allow", rules: [ Rule.allowEgress(Destination.cidr("10.0.0.0/8")), // matches everything in 10.x Rule.denyEgress(Destination.cidr("10.0.0.5/32")), // never reached ], }; ``` Put specific rules before general ones. ### Shadow detection [`NetworkPolicyBuilder.build()`](#build) walks the rules and warns when a rule is fully covered by an earlier one in the same direction. Only `cidr` and `group` destinations are checked; domain coverage depends on runtime DNS and is skipped. Builds still succeed; the warning surfaces as a host-side `tracing::warn!` from the rust core: ```text WARN rule #1 (Egress Cidr(10.0.0.5/32) Deny) is shadowed by rule #0 (Egress Cidr(10.0.0.0/8) Allow); to narrow, place the more specific rule first ``` Policy literals constructed via `Rule.allowEgress(...)` etc. do not run through the builder and skip this check. --- #### NetworkPolicy.builder()
factory
```typescript builder(): NetworkPolicyBuilder ``` Start the fluent [`NetworkPolicyBuilder`](#networkpolicybuilder). Equivalent to `new NetworkPolicyBuilder()`. String inputs (`.ip()`, `.cidr()`, `.domain()`, `.domainSuffix()`) are stored raw and parsed at [`build()`](#build), so the chain stays clean and the first parse or validation failure surfaces there.

Returns

NetworkPolicyBuilder
Empty builder.
```typescript import { NetworkPolicy } from "microsandbox"; const policy = NetworkPolicy.builder() .defaultDeny() .egress((e) => e.tcp().port(443).allowPublic().allowPrivate()) .build(); ``` --- #### NetworkPolicy.none()
factory
```typescript none(): NetworkPolicy ``` Deny all traffic in both directions, no rules. The guest is fully offline. `exec` and `fs` still work since they use the host-guest channel, not the network. --- #### NetworkPolicy.allowAll()
factory
```typescript allowAll(): NetworkPolicy ``` Unrestricted network access: allow everything in both directions, no rules. Includes private addresses and the host machine. --- #### NetworkPolicy.publicOnly()
factory
```typescript publicOnly(): NetworkPolicy ``` Egress allowed only to public destinations (plus DNS to the gateway); ingress allowed by default. Blocks private address ranges and cloud metadata endpoints. This is the **default** policy. --- #### NetworkPolicy.nonLocal()
factory
```typescript nonLocal(): NetworkPolicy ``` Egress allowed to public + private (LAN) destinations (plus DNS); ingress allowed by default. Local groups (loopback, link-local, host, metadata) stay denied. --- ## Rule, Destination, PortRange Factories for the building blocks of a policy literal. [`Rule`](#rule-2) values pair a [`Destination`](#destination) with a direction and action; [`Destination`](#destination) and [`PortRange`](#portrange-2) construct the matchers. --- #### Rule.allowEgress()
factory
```typescript allowEgress(destination: Destination): Rule ``` Allow rule with direction `egress`. Empty protocols and ports mean "any".

Parameters

destinationDestination
Target filter.
```typescript import { Rule, Destination } from "microsandbox"; const r = Rule.allowEgress(Destination.domain("api.example.com")); ``` --- #### Rule.denyEgress()
factory
```typescript denyEgress(destination: Destination): Rule ``` Deny rule with direction `egress`.

Parameters

destinationDestination
Target filter.
--- #### Rule.allowIngress()
factory
```typescript allowIngress(destination: Destination): Rule ``` Allow rule with direction `ingress`.

Parameters

destinationDestination
Target filter.
--- #### Rule.denyIngress()
factory
```typescript denyIngress(destination: Destination): Rule ``` Deny rule with direction `ingress`.

Parameters

destinationDestination
Target filter.
--- #### Rule.allowAny()
factory
```typescript allowAny(destination: Destination): Rule ``` Allow rule with direction `any` (matches in either direction).

Parameters

destinationDestination
Target filter.
--- #### Rule.denyAny()
factory
```typescript denyAny(destination: Destination): Rule ``` Deny rule with direction `any` (matches in either direction).

Parameters

destinationDestination
Target filter.
--- #### Rule.allowDns()
factory
```typescript allowDns(): Rule ``` 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](/networking/dns#dns-as-egress) for the underlying semantics. DoT (TCP/853) is intentionally not included; add an explicit `Destination.group("host")` tcp/853 allow rule if needed (and pair with TLS interception). ```typescript import { NetworkPolicy, Rule } from "microsandbox"; const policy: NetworkPolicy = { defaultEgress: "deny", defaultIngress: "deny", rules: [Rule.allowDns()], }; ``` --- #### Destination.any()
factory
```typescript any(): Destination ``` Match any destination. --- #### Destination.cidr()
factory
```typescript cidr(cidr: string): Destination ``` Match an IP range.

Parameters

cidrstring
CIDR notation, e.g. "10.0.0.0/8".
--- #### Destination.domain()
factory
```typescript domain(domain: string): Destination ``` Match an exact domain.

Parameters

domainstring
Fully qualified domain name.
--- #### Destination.domainSuffix()
factory
```typescript domainSuffix(suffix: string): Destination ``` Match the apex domain and every subdomain.

Parameters

suffixstring
Domain suffix.
--- #### Destination.group()
factory
```typescript group(group: DestinationGroup): Destination ``` Match a predefined address group.

Parameters

groupDestinationGroup
Group keyword.
--- #### PortRange.single()
factory
```typescript single(port: number): PortRange ``` Match a single port. `start` and `end` are set to the same value.

Parameters

portnumber
Port number.
--- #### PortRange.range()
factory
```typescript range(start: number, end: number): PortRange ``` Match an inclusive port range.

Parameters

startnumber
Lower bound (inclusive).
endnumber
Upper bound (inclusive).
--- ## NetworkBuilder Passed to the callback you give `SandboxBuilder.network(...)`. Every setter returns the same builder. The runtime serializes the accumulated config when the sandbox is created. --- #### .policy()
builder
```typescript policy(policy: NetworkPolicy | NetworkPolicyBuilder): this ``` Set the policy. Accepts a [`NetworkPolicy`](#networkpolicy-2) literal or factory result, or a [`NetworkPolicyBuilder`](#networkpolicybuilder) (routed through the native bridge so lazy parse/validation errors surface at this call site).

Parameters

policyNetworkPolicy
Policy literal, factory result, or builder.
```typescript import { NetworkPolicy, Sandbox } from "microsandbox"; const sb = await Sandbox.builder("api") .image("python") .network((n) => n.policy(NetworkPolicy.publicOnly())) .create(); ``` --- #### .port()
builder
```typescript port(host: number, guest: number): this ``` Publish a TCP port from the guest to the host. The default host bind address is `127.0.0.1`.

Parameters

hostnumber
Port on the host.
guestnumber
Port inside the sandbox.
--- #### .portBind()
builder
```typescript portBind(bind: string, host: number, guest: number): this ``` Publish a TCP port on a specific host bind address, such as `0.0.0.0`.

Parameters

bindstring
Host bind address.
hostnumber
Port on the host.
guestnumber
Port inside the sandbox.
--- #### .portUdp()
builder
```typescript portUdp(host: number, guest: number): this ``` Publish a UDP port from the guest to the host. The default host bind address is `127.0.0.1`.

Parameters

hostnumber
Port on the host.
guestnumber
Port inside the sandbox.
--- #### .portUdpBind()
builder
```typescript portUdpBind(bind: string, host: number, guest: number): this ``` Publish a UDP port on a specific host bind address.

Parameters

bindstring
Host bind address.
hostnumber
Port on the host.
guestnumber
Port inside the sandbox.
--- #### .dns()
builder
```typescript dns(configure: (b: DnsBuilder) => DnsBuilder): this ``` Configure DNS interception. See [`DnsBuilder`](#dnsbuilder).

Parameters

configureDnsBuilder
Configure DNS.
```typescript .network((n) => n.dns((d) => d.rebindProtection(true).queryTimeoutMs(2000))) ``` --- #### .tls()
builder
```typescript tls(configure: (b: TlsBuilder) => TlsBuilder): this ``` Configure TLS interception. See [`TlsBuilder`](#tlsbuilder).

Parameters

configureTlsBuilder
Configure TLS.
--- #### .trustHostCAs()
builder
```typescript trustHostCAs(enabled: boolean): this ``` Whether to ship the host's trusted root CAs into the guest at boot. Default: `false`. Opt in for corporate MITM proxies (Cloudflare Warp Zero Trust, Zscaler, Netskope, etc.) whose gateway CA is installed on the host but unknown to the guest's stock Mozilla bundle.

Parameters

enabledboolean
Ship host CAs into the guest.
--- #### .maxConnections()
builder
```typescript maxConnections(max: number): this ``` Limit the maximum number of concurrent network connections from the sandbox.

Parameters

maxnumber
Maximum concurrent connections.
--- #### .ipv4Pool()
builder
```typescript ipv4Pool(pool: string): this ``` Set the IPv4 pool used to derive per-sandbox `/30` guest subnets. Defaults to `172.16.0.0/12`.

Parameters

poolstring
IPv4 CIDR pool.
--- #### .ipv6Pool()
builder
```typescript ipv6Pool(pool: string): this ``` Set the IPv6 pool used to derive per-sandbox `/64` guest prefixes. Defaults to `fd42:6d73:62::/48`.

Parameters

poolstring
IPv6 CIDR pool.
--- #### .interface()
builder
```typescript interface(configure: (b: InterfaceOverridesBuilder) => InterfaceOverridesBuilder): this ``` Override per-sandbox interface attributes (MAC, MTU, fixed IPv4 / IPv6 address). The [`InterfaceOverridesBuilder`](#interfaceoverridesbuilder) exposes `.mac()`, `.mtu()`, `.ipv4()`, and `.ipv6()`.

Parameters

configureInterfaceOverridesBuilder
Configure interface overrides.
```typescript .network((n) => n.interface((i) => i.mtu(1400).ipv4("172.16.0.2"))) ``` --- #### .enabled()
builder
```typescript enabled(enabled: boolean): this ``` Enable or disable networking entirely. When `false`, no network interface is created.

Parameters

enabledboolean
Master enable flag.
--- #### .onSecretViolation()
builder
```typescript onSecretViolation(configure: (b: ViolationActionBuilder) => ViolationActionBuilder): this ``` Configure the action taken when a secret reaches a disallowed host. See [`ViolationActionBuilder`](#violationactionbuilder).

Parameters

configureViolationActionBuilder
Configure the violation action.
```typescript .network((n) => n.onSecretViolation((v) => v.blockAndLog().passthroughHost("api.anthropic.com"), ), ) ``` Passthrough hosts receive placeholders unchanged. They do **not** receive real secret values. --- #### .secret()
builder
```typescript secret(configure: (b: SecretBuilder) => SecretBuilder): this ``` Add a secret with full configuration. See [`SecretBuilder`](/sdk/typescript/secrets#secretbuilder).

Parameters

configureSecretBuilder
Configure the secret.
--- #### .secretEnv()
builder
```typescript secretEnv(envVar: string, value: string, placeholder: string, allowedHost: string): this ``` Four-arg explicit-placeholder shorthand for adding a secret without opening a builder callback.

Parameters

envVarstring
Environment variable name (non-empty, no = or NUL).
valuestring
Real secret value.
placeholderstring
Placeholder string: non-empty, up to 1024 bytes, no NUL/CR/LF.
allowedHoststring
Single hostname allowed to receive the real value.
--- #### .secretEnvSimple()
builder
```typescript secretEnvSimple(envVar: string, value: string, allowedHost: string): this ``` Three-arg auto-placeholder shorthand. Auto-generates the placeholder as `$MSB_`, so it is the terse counterpart to [`secretEnv()`](#secretenv) when you do not need a custom placeholder. The full secret API also lives on the [secrets page](/sdk/typescript/secrets#networkbuilder-secretenvsimple).

Parameters

envVarstring
Environment variable name (non-empty, no = or NUL).
valuestring
Real secret value.
allowedHoststring
Single hostname allowed to receive the real value.
```typescript .network((n) => n.secretEnvSimple("OPENAI_API_KEY", process.env.OPENAI_API_KEY!, "api.openai.com"), ) ``` --- #### .build()
builder
```typescript build(): NetworkConfig ``` Materialize the accumulated state into a [`NetworkConfig`](#networkconfig). The native bridge returns snake_case serde output, which the wrapper remaps to camelCase keys before handing back a plain JS object. Inside `SandboxBuilder.network(...)` the runtime calls this for you; call it directly only when you want to inspect or persist the resolved config.

Returns

NetworkConfig
The materialized network configuration.
--- ## NetworkPolicyBuilder Fluent builder for [`NetworkPolicy`](#networkpolicy-2). The closure passed to `.rule()` / `.egress()` / `.ingress()` / `.any()` receives a [`RuleBuilder`](#rulebuilder); state setters and rule-adders chain freely. The first parse / validation failure surfaces from [`build()`](#build). ```typescript import { NetworkPolicy } from "microsandbox"; const policy = NetworkPolicy.builder() .defaultDeny() .egress((e) => e.tcp().port(443).allowPublic().allowPrivate()) .rule((r) => r.any().deny((d) => d.ip("198.51.100.5"))) .build(); ``` --- #### .defaultDeny()
builder
```typescript defaultDeny(): this ``` Set both `defaultEgress` and `defaultIngress` to `"deny"`. --- #### .defaultAllow()
builder
```typescript defaultAllow(): this ``` Set both `defaultEgress` and `defaultIngress` to `"allow"`. --- #### .defaultEgress()
builder
```typescript defaultEgress(action: "allow" | "deny"): this ``` Per-direction override for the egress default action.

Parameters

action"allow" | "deny"
Default action for egress.
--- #### .defaultIngress()
builder
```typescript defaultIngress(action: "allow" | "deny"): this ``` Per-direction override for the ingress default action.

Parameters

action"allow" | "deny"
Default action for ingress.
--- #### .egress()
builder
```typescript egress(configure: (rb: RuleBuilder) => RuleBuilder): this ``` Sugar for [`rule()`](#rule) with direction pre-set to `egress`.

Parameters

configureRuleBuilder
Add egress rules.
--- #### .ingress()
builder
```typescript ingress(configure: (rb: RuleBuilder) => RuleBuilder): this ``` Sugar for [`rule()`](#rule) with direction pre-set to `ingress`.

Parameters

configureRuleBuilder
Add ingress rules.
--- #### .any()
builder
```typescript any(configure: (rb: RuleBuilder) => RuleBuilder): this ``` Sugar for [`rule()`](#rule) with direction pre-set to `any`. Rules committed inside apply in both directions.

Parameters

configureRuleBuilder
Add bidirectional rules.
--- #### .rule()
builder
```typescript rule(configure: (rb: RuleBuilder) => RuleBuilder): this ``` Open a multi-rule batch closure. Direction must be set inside via `.egress()`, `.ingress()`, or `.any()` before any rule-adder.

Parameters

configureRuleBuilder
Add rules; set direction first.
--- #### .build()
builder
```typescript build(): NetworkPolicy ``` Materialize the accumulated state into a [`NetworkPolicy`](#networkpolicy-2). Lazily parses every recorded `.ip()` / `.cidr()` / `.domain()` / `.domainSuffix()` input, validates direction-set and ICMP-egress-only invariants, and emits a host-side warning for each shadowed rule pair.

Returns

NetworkPolicy
The materialized policy.
--- ## RuleBuilder Per-rule-batch builder. Lives only inside the callback passed to `.rule()` / `.egress()` / `.ingress()` / `.any()` on a [`NetworkPolicyBuilder`](#networkpolicybuilder). State setters and rule-adders interleave freely; state accumulates eagerly across the callback and is **not reset** between adders: ```typescript NetworkPolicy.builder() .egress((r) => r .tcp().port(443).allowPublic() // rule 1: egress, TCP, 443, allow Public .udp().allowPrivate(), // rule 2: egress, [TCP, UDP], 443, allow Private ) .build(); ``` Use separate `.rule()` / `.egress()` callbacks for rules that need different state. ### Direction setters Last-write-wins. ICMP rule-adders are egress-only at build time. --- #### .egress()
builder
```typescript egress(): this ``` Set direction to `egress` for subsequent rule-adders. --- #### .ingress()
builder
```typescript ingress(): this ``` Set direction to `ingress` for subsequent rule-adders. --- #### .any()
builder
```typescript any(): this ``` Set direction to `any` for subsequent rule-adders. Rules committed after this apply in both directions. --- ### Protocol setters Protocols accumulate as a set; duplicates dedupe. --- #### .tcp()
builder
```typescript tcp(): this ``` Add `tcp` to the protocols set. --- #### .udp()
builder
```typescript udp(): this ``` Add `udp` to the protocols set. --- #### .icmpv4()
builder
```typescript icmpv4(): this ``` Add `icmpv4` to the protocols set. Egress-only; an ICMP rule on an `ingress` or `any` direction fails build. --- #### .icmpv6()
builder
```typescript icmpv6(): this ``` Add `icmpv6` to the protocols set. Egress-only; same rules as [`icmpv4()`](#icmpv4). --- ### Port setters Ports accumulate as a set; duplicates dedupe. Always guest-side (egress destination port / ingress listening port). --- #### .port()
builder
```typescript port(port: number): this ``` Add a single port to the ports set.

Parameters

portnumber
Port number 0..=65535.
--- #### .portRange()
builder
```typescript portRange(lo: number, hi: number): this ``` Add an inclusive port range. `lo > hi` records an error surfaced at [`build()`](#build) time.

Parameters

lonumber
Lower bound (inclusive).
hinumber
Upper bound (inclusive).
--- #### .ports()
builder
```typescript ports(ports: number[]): this ``` Add multiple single ports. Equivalent to calling [`port()`](#port-1) once per element.

Parameters

portsnumber[]
Port numbers.
--- ### Group rule-adders Each adder commits one rule using the current state and the named destination group. --- #### .allowPublic()
builder
```typescript allowPublic(): this ``` Allow the `public` group (complement of named categories: every IP not in any other group). --- #### .denyPublic()
builder
```typescript denyPublic(): this ``` Deny the `public` group. --- #### .allowPrivate()
builder
```typescript allowPrivate(): this ``` Allow the `private` group (RFC1918 + ULA + CGN). --- #### .denyPrivate()
builder
```typescript denyPrivate(): this ``` Deny the `private` group. --- #### .allowLoopback()
builder
```typescript allowLoopback(): this ``` Allow the `loopback` 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 [`allowHost()`](#allowhost) instead. See the [loopback-vs-host watch-out](/networking/overview#loopback-vs-host-a-common-trap). --- #### .denyLoopback()
builder
```typescript denyLoopback(): this ``` Deny the `loopback` group. --- #### .allowLinkLocal()
builder
```typescript allowLinkLocal(): this ``` Allow the `link-local` group (`169.254.0.0/16`, `fe80::/10`). Excludes the metadata IP `169.254.169.254`. --- #### .denyLinkLocal()
builder
```typescript denyLinkLocal(): this ``` Deny the `link-local` group. --- #### .allowMeta()
builder
```typescript allowMeta(): this ``` Allow the `metadata` group (`169.254.169.254`). **Dangerous on cloud hosts** (exposes IAM credentials). --- #### .denyMeta()
builder
```typescript denyMeta(): this ``` Deny the `metadata` group. --- #### .allowMulticast()
builder
```typescript allowMulticast(): this ``` Allow the `multicast` group (`224.0.0.0/4`, `ff00::/8`). --- #### .denyMulticast()
builder
```typescript denyMulticast(): this ``` Deny the `multicast` group. --- #### .allowHost()
builder
```typescript allowHost(): this ``` Allow the `host` 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 [`allowLoopback()`](#allowloopback). --- #### .denyHost()
builder
```typescript denyHost(): this ``` Deny the `host` group. --- ### Composite rule-adders --- #### .allowLocal()
builder
```typescript allowLocal(): this ``` Add three allow rules atomically: `loopback + link-local + host`. Each uses the callback's current state. `metadata` is intentionally not included; opt in via [`allowMeta()`](#allowmeta) separately. --- #### .denyLocal()
builder
```typescript denyLocal(): this ``` Add three deny rules atomically: `loopback + link-local + host`. `metadata` is intentionally not included. --- ### Domain rule-adders Singular forms add one rule; plural forms add one rule per element. --- #### .allowDomain()
builder
```typescript allowDomain(name: string): this ``` Add one `Destination::Domain` allow rule.

Parameters

namestring
Fully qualified domain name.
--- #### .denyDomain()
builder
```typescript denyDomain(name: string): this ``` Add one `Destination::Domain` deny rule.

Parameters

namestring
Fully qualified domain name.
--- #### .allowDomains()
builder
```typescript allowDomains(names: string[]): this ``` Add one `Destination::Domain` allow rule per name.

Parameters

namesstring[]
Fully qualified domain names.
--- #### .denyDomains()
builder
```typescript denyDomains(names: string[]): this ``` Add one `Destination::Domain` deny rule per name.

Parameters

namesstring[]
Fully qualified domain names.
--- #### .allowDomainSuffix()
builder
```typescript allowDomainSuffix(suffix: string): this ``` Add one `Destination::DomainSuffix` allow rule. Matches the apex and any subdomain.

Parameters

suffixstring
Domain suffix.
--- #### .denyDomainSuffix()
builder
```typescript denyDomainSuffix(suffix: string): this ``` Add one `Destination::DomainSuffix` deny rule. Matches the apex and any subdomain.

Parameters

suffixstring
Domain suffix.
--- #### .allowDomainSuffixes()
builder
```typescript allowDomainSuffixes(suffixes: string[]): this ``` Add one `Destination::DomainSuffix` allow rule per suffix.

Parameters

suffixesstring[]
Domain suffixes.
--- #### .denyDomainSuffixes()
builder
```typescript denyDomainSuffixes(suffixes: string[]): this ``` Add one `Destination::DomainSuffix` deny rule per suffix.

Parameters

suffixesstring[]
Domain suffixes.
--- ### Explicit-destination rule-adders `.allow()` / `.deny()` open a [`RuleDestinationBuilder`](#ruledestinationbuilder) callback. Exactly one destination call commits the rule. ```typescript NetworkPolicy.builder() .egress((r) => r .tcp().port(443).allow((d) => d.domain("api.example.com")) .deny((d) => d.cidr("198.51.100.0/24")), ) .build(); ``` --- #### .allow()
builder
```typescript allow(configure: (d: RuleDestinationBuilder) => RuleDestinationBuilder): this ``` Begin an explicit-destination rule with action `allow`.

Parameters

configureRuleDestinationBuilder
Commit exactly one destination.
--- #### .deny()
builder
```typescript deny(configure: (d: RuleDestinationBuilder) => RuleDestinationBuilder): this ``` Begin an explicit-destination rule with action `deny`.

Parameters

configureRuleDestinationBuilder
Commit exactly one destination.
--- ## RuleDestinationBuilder Returned by [`RuleBuilder`](#rulebuilder)`.allow(d => ...)` / `.deny(d => ...)`. Exactly one destination call commits the rule; dropping without a destination call silently does nothing. --- #### .ip()
builder
```typescript ip(ip: string): this ``` Commit with `Destination::Cidr` of the IP as `/32` or `/128`.

Parameters

ipstring
Single IPv4 or IPv6 address.
--- #### .cidr()
builder
```typescript cidr(cidr: string): this ``` Commit with `Destination::Cidr`.

Parameters

cidrstring
CIDR notation.
--- #### .domain()
builder
```typescript domain(domain: string): this ``` Commit with `Destination::Domain`.

Parameters

domainstring
Fully qualified domain name.
--- #### .domainSuffix()
builder
```typescript domainSuffix(suffix: string): this ``` Commit with `Destination::DomainSuffix`.

Parameters

suffixstring
Domain suffix.
--- #### .group()
builder
```typescript group(group: string): this ``` Commit with `Destination::Group`. `group` is a [`DestinationGroup`](#destinationgroup) string.

Parameters

groupDestinationGroup
Group keyword.
--- #### .any()
builder
```typescript any(): this ``` Commit with `Destination::Any`. --- ## DnsBuilder Builder for DNS interception settings. Used in `NetworkBuilder.dns(d => ...)`. Owns rebind protection, nameserver pinning, and the per-query timeout. --- #### .rebindProtection()
builder
```typescript rebindProtection(enabled: boolean): this ``` Toggle DNS rebinding protection. When enabled, DNS responses resolving to private IPs are blocked.

Parameters

enabledboolean
Enable rebinding protection.
--- #### .nameservers()
builder
```typescript nameservers(servers: string[]): this ``` Override upstream nameservers. Replaces any previously-set nameservers.

Parameters

serversstring[]
Each entry is IP, IP:PORT, HOST, or HOST:PORT.
--- #### .queryTimeoutMs()
builder
```typescript queryTimeoutMs(ms: number): this ``` Per-DNS-query timeout in milliseconds.

Parameters

msnumber
Timeout in milliseconds.
--- ## TlsBuilder Builder for TLS interception settings. Used in `NetworkBuilder.tls(t => ...)`. --- #### .bypass()
builder
```typescript bypass(pattern: string): this ``` Skip TLS interception for hosts matching this glob (e.g. `"*.internal.corp"`). Use for domains with certificate pinning.

Parameters

patternstring
Glob pattern.
--- #### .verifyUpstream()
builder
```typescript verifyUpstream(verify: boolean): this ``` Verify upstream server certificates. Default `true`. Set to `false` only for self-signed servers.

Parameters

verifyboolean
Verify upstream certs.
--- #### .verifyUpstreamFor()
builder
```typescript verifyUpstreamFor(pattern: string, verify: boolean): this ``` Verify 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. --- #### .interceptedPorts()
builder
```typescript interceptedPorts(ports: number[]): this ``` TCP ports where interception is active. Default: `[443]`.

Parameters

portsnumber[]
Intercepted TCP ports.
--- #### .blockQuic()
builder
```typescript blockQuic(block: boolean): this ``` Block QUIC on intercepted ports, forcing TCP/TLS fallback.

Parameters

blockboolean
Block QUIC.
--- #### .interceptCaCert()
builder
```typescript interceptCaCert(path: string): this ``` Path to a PEM file used as the intercepting CA's certificate.

Parameters

pathstring
PEM cert path.
--- #### .interceptCaKey()
builder
```typescript interceptCaKey(path: string): this ``` Path to a PEM file used as the intercepting CA's private key.

Parameters

pathstring
PEM key path.
--- #### .upstreamCaCert()
builder
```typescript upstreamCaCert(path: string): this ``` Path to a PEM file with extra root CAs the proxy should trust when verifying every upstream server.

Parameters

pathstring
PEM cert path.
--- #### .upstreamCaCertFor()
builder
```typescript upstreamCaCertFor(pattern: string, path: string): this ``` Path to a 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. --- ## ViolationActionBuilder Configures the action taken when a secret would be sent to a disallowed host. Used in `NetworkBuilder.onSecretViolation(v => ...)`. Passthrough host calls accumulate; when passthrough hosts are configured, non-matching hosts use the default secret-violation action. --- #### .block()
builder
```typescript block(): this ``` Block the request silently. --- #### .blockAndLog()
builder
```typescript blockAndLog(): this ``` Block the request and emit a warning log. --- #### .blockAndTerminate()
builder
```typescript blockAndTerminate(): this ``` Block the request and terminate the sandbox. --- #### .passthroughHost()
builder
```typescript passthroughHost(host: string): this ``` Allow placeholders to pass through unchanged to an exact host. The host receives the placeholder, not the real secret value.

Parameters

hoststring
Exact host.
--- #### .passthroughHostPattern()
builder
```typescript passthroughHostPattern(pattern: string): this ``` Allow placeholders to pass through unchanged to matching wildcard hosts.

Parameters

patternstring
Wildcard host pattern.
--- #### .passthroughAllHosts()
builder
```typescript passthroughAllHosts(iUnderstand: boolean): this ``` Allow placeholders to pass through unchanged to any host. The explicit `iUnderstand` flag must be `true` to acknowledge the broad scope.

Parameters

iUnderstandboolean
Must be true to opt in.
## Types ### NetworkConfig
interface

Returned by NetworkBuilder.build()

Built network configuration produced by `NetworkBuilder.build()`. Keys are camelCased from the Rust serde output. | Field | Type | Description | |-------|------|-------------| | enabled | `boolean` | Master enable flag | | ports | `readonly `[`PublishedPort`](#publishedport)`[]` | Port publishings | | policy | [`NetworkPolicy`](#networkpolicy-2) ` \| null` | Active policy | | dns | [`DnsConfig`](#dnsconfig) ` \| null` | DNS interception | | tls | [`TlsConfig`](#tlsconfig) ` \| null` | TLS interception | | secrets | `readonly SecretEntry[]` | Secret entries | | secretViolation | [`ViolationAction`](/sdk/typescript/secrets#violationaction) ` \| null` | Action on disallowed secret use | | maxConnections | `number \| null` | Maximum concurrent connections | | interface | `{ ipv4Pool?, ipv6Pool?, ipv4Address?, ipv6Address?, mac?, mtu? }` | Optional interface overrides | | trustHostCAs | `boolean` | Ship host CAs into the guest | ### NetworkPolicy
interface

Used by NetworkBuilder.policy() · returned by NetworkPolicy factories

Ordered rule list with per-direction defaults. First-match-wins is evaluated independently for egress and ingress. ```typescript interface NetworkPolicy { readonly defaultEgress: Action; readonly defaultIngress: Action; readonly rules: readonly Rule[]; } ``` ### Rule
interface

Used by NetworkPolicy.rules · built via Rule factories

A single ordered policy rule. ```typescript interface Rule { readonly direction: Direction; readonly destination: Destination; readonly protocols: readonly Protocol[]; // empty = any readonly ports: readonly PortRange[]; // empty = any readonly action: Action; } ``` ### Action
type

Used by Rule.action · NetworkPolicy defaults

Action taken on a matching rule (or the per-direction default). ```typescript type Action = "allow" | "deny"; ``` ### Direction
type

Used by Rule.direction

Direction the rule applies to. ```typescript type Direction = "egress" | "ingress" | "any"; ``` ### Destination
type

Used by Rule.destination · built via Destination factories

Destination filter. An internally-tagged union; use the [`Destination`](#destination) factory for constructors. ```typescript type Destination = | { kind: "any" } | { kind: "cidr"; cidr: string } | { kind: "domain"; domain: string } | { kind: "domainSuffix"; suffix: string } | { kind: "group"; group: DestinationGroup }; ``` ### DestinationGroup
type

Used by Destination.group() · RuleDestinationBuilder.group()

Predefined address group keyword. The runtime constant `DestinationGroups` lists all values. ```typescript type DestinationGroup = | "public" | "loopback" | "private" | "link-local" | "metadata" | "multicast" | "host"; ``` | Value | Description | |-------|-------------| | `'public'` | Public internet (everything not in another group) | | `'loopback'` | Guest's own `127.0.0.0/8` / `::1` | | `'private'` | RFC1918 LAN ranges (+ ULA + CGN) | | `'link-local'` | `169.254.0.0/16` / `fe80::/10` | | `'metadata'` | Cloud metadata endpoint (`169.254.169.254`) | | `'multicast'` | `224.0.0.0/4` / `ff00::/8` | | `'host'` | The host machine, reached via `host.microsandbox.internal` | ### Protocol
type

Used by Rule.protocols

Transport protocol filter. Empty `Rule.protocols` means "any protocol". ```typescript type Protocol = "tcp" | "udp" | "icmpv4" | "icmpv6"; ``` ### PortRange
interface

Used by Rule.ports · built via PortRange factories

Inclusive port range. Always interpreted as the guest-side port. ```typescript interface PortRange { readonly start: number; readonly end: number; } ``` ### PublishedPort
interface

Used by NetworkConfig.ports

A published port mapping from the guest to the host. ```typescript interface PublishedPort { readonly hostPort: number; readonly guestPort: number; readonly protocol: "tcp" | "udp"; readonly hostBind: string; } ``` ### DnsConfig
interface

Used by NetworkConfig.dns

DNS interception configuration. | Field | Type | Description | |-------|------|-------------| | nameservers | `readonly string[]` | Upstream nameservers | | rebindProtection | `boolean \| null` | DNS rebinding protection toggle | | queryTimeoutMs | `number \| null` | Per-query timeout | ### TlsConfig
interface

Used by NetworkConfig.tls

TLS interception configuration. | Field | Type | Description | |-------|------|-------------| | bypass | `readonly string[]` | Bypass globs (e.g. `"*.googleapis.com"`) | | verifyUpstream | `boolean \| null` | Verify upstream certs | | interceptedPorts | `readonly number[]` | Intercepted TCP ports | | blockQuic | `boolean \| null` | Block QUIC on intercepted ports | | upstreamCaCertPaths | `readonly string[]` | Extra trust roots for upstream verification | | scopedUpstreamCaCerts | `readonly ScopedUpstreamCaCert[]` | Host-scoped extra trust roots for upstream verification | | scopedVerifyUpstream | `readonly ScopedVerifyUpstream[]` | Host-scoped upstream certificate verification overrides | | interceptCaCertPath | `string \| null` | Custom intercept CA cert (PEM) | | interceptCaKeyPath | `string \| null` | Custom intercept CA key (PEM) | ### ScopedUpstreamCaCert | Field | Type | Description | |-------|------|-------------| | pattern | `string` | Exact host or `*.suffix` wildcard | | path | `string` | CA bundle path trusted for matching upstream hosts | ### ScopedVerifyUpstream | Field | Type | Description | |-------|------|-------------| | pattern | `string` | Exact host or `*.suffix` wildcard | | verify | `boolean` | Whether to verify certificates for matching upstream hosts | ### InterfaceOverridesBuilder
builder

Used by NetworkBuilder.interface()

Builder for per-sandbox network interface overrides. | Method | Description | |--------|-------------| | `.mac(mac)` | Set the interface MAC address | | `.mtu(mtu)` | Set the interface MTU | | `.ipv4(address)` | Pin a fixed IPv4 address | | `.ipv6(address)` | Pin a fixed IPv6 address |