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.
#### `, 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.
#### network.build()
```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
The materialized network configuration.
## NetworkPolicyBuilder
Fluent builder for [`NetworkPolicy`](#networkpolicy-2).
#### policy.defaultDeny()
```typescript
defaultDeny(): this
```
Set both `defaultEgress` and `defaultIngress` to `"deny"`.
#### policy.defaultAllow()
```typescript
defaultAllow(): this
```
Set both `defaultEgress` and `defaultIngress` to `"allow"`.
#### policy.defaultEgress()
```typescript
defaultEgress(action: "allow" | "deny"): this
```
Per-direction override for the egress default action.
Parameters
action"allow" | "deny"
Default action for egress.
#### policy.defaultIngress()
```typescript
defaultIngress(action: "allow" | "deny"): this
```
Per-direction override for the ingress default action.
Parameters
action"allow" | "deny"
Default action for ingress.
#### policy.egress()
```typescript
egress(configure: (rb: RuleBuilder) => RuleBuilder): this
```
Sugar for [`rule()`](#rule) with direction pre-set to `egress`.
Parameters
#### policy.ingress()
```typescript
ingress(configure: (rb: RuleBuilder) => RuleBuilder): this
```
Sugar for [`rule()`](#rule) with direction pre-set to `ingress`.
Parameters
#### policy.any()
```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
#### policy.rule()
```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
Add rules; set direction first.
#### policy.build()
```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
## RuleBuilder
Builder for one policy-rule batch.
#### rule.egress()
```typescript
egress(): this
```
Set direction to `egress` for subsequent rule-adders.
#### rule.ingress()
```typescript
ingress(): this
```
Set direction to `ingress` for subsequent rule-adders.
#### rule.any()
```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.
#### rule.tcp()
```typescript
tcp(): this
```
Add `tcp` to the protocols set.
#### rule.udp()
```typescript
udp(): this
```
Add `udp` to the protocols set.
#### rule.icmpv4()
```typescript
icmpv4(): this
```
Add `icmpv4` to the protocols set. Egress-only; an ICMP rule on an `ingress` or `any` direction fails build.
#### rule.icmpv6()
```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).
#### rule.port()
```typescript
port(port: number): this
```
Add a single port to the ports set.
Parameters
portnumber
Port number 0..=65535.
#### rule.portRange()
```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).
#### rule.ports()
```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.
#### rule.allowPublic()
```typescript
allowPublic(): this
```
Allow the `public` group (complement of named categories: every IP not in any other group).
#### rule.denyPublic()
```typescript
denyPublic(): this
```
Deny the `public` group.
#### rule.allowPrivate()
```typescript
allowPrivate(): this
```
Allow the `private` group (RFC1918 + ULA + CGN).
#### rule.denyPrivate()
```typescript
denyPrivate(): this
```
Deny the `private` group.
#### rule.allowLoopback()
```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).
#### rule.denyLoopback()
```typescript
denyLoopback(): this
```
Deny the `loopback` group.
#### rule.allowLinkLocal()
```typescript
allowLinkLocal(): this
```
Allow the `link-local` group (`169.254.0.0/16`, `fe80::/10`). Excludes the metadata IP `169.254.169.254`.
#### rule.denyLinkLocal()
```typescript
denyLinkLocal(): this
```
Deny the `link-local` group.
#### rule.allowMeta()
```typescript
allowMeta(): this
```
Allow the `metadata` group (`169.254.169.254`). **Dangerous on cloud hosts** (exposes IAM credentials).
#### rule.denyMeta()
```typescript
denyMeta(): this
```
Deny the `metadata` group.
#### rule.allowMulticast()
```typescript
allowMulticast(): this
```
Allow the `multicast` group (`224.0.0.0/4`, `ff00::/8`).
#### rule.denyMulticast()
```typescript
denyMulticast(): this
```
Deny the `multicast` group.
#### rule.allowHost()
```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).
#### rule.denyHost()
```typescript
denyHost(): this
```
Deny the `host` group.
### Composite rule-adders
#### rule.allowLocal()
```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.
#### rule.denyLocal()
```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.
#### rule.allowDomain()
```typescript
allowDomain(name: string): this
```
Add one `Destination::Domain` allow rule.
Parameters
namestring
Fully qualified domain name.
#### rule.denyDomain()
```typescript
denyDomain(name: string): this
```
Add one `Destination::Domain` deny rule.
Parameters
namestring
Fully qualified domain name.
#### rule.allowDomains()
```typescript
allowDomains(names: string[]): this
```
Add one `Destination::Domain` allow rule per name.
Parameters
namesstring[]
Fully qualified domain names.
#### rule.denyDomains()
```typescript
denyDomains(names: string[]): this
```
Add one `Destination::Domain` deny rule per name.
Parameters
namesstring[]
Fully qualified domain names.
#### rule.allowDomainSuffix()
```typescript
allowDomainSuffix(suffix: string): this
```
Add one `Destination::DomainSuffix` allow rule. Matches the apex and any subdomain.
Parameters
suffixstring
Domain suffix.
#### rule.denyDomainSuffix()
```typescript
denyDomainSuffix(suffix: string): this
```
Add one `Destination::DomainSuffix` deny rule. Matches the apex and any subdomain.
Parameters
suffixstring
Domain suffix.
#### rule.allowDomainSuffixes()
```typescript
allowDomainSuffixes(suffixes: string[]): this
```
Add one `Destination::DomainSuffix` allow rule per suffix.
Parameters
suffixesstring[]
Domain suffixes.
#### rule.denyDomainSuffixes()
```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();
```
#### rule.allow()
```typescript
allow(configure: (d: RuleDestinationBuilder) => RuleDestinationBuilder): this
```
Begin an explicit-destination rule with action `allow`.
Parameters
Commit exactly one destination.
#### rule.deny()
```typescript
deny(configure: (d: RuleDestinationBuilder) => RuleDestinationBuilder): this
```
Begin an explicit-destination rule with action `deny`.
Parameters
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.
#### destination.ip()
```typescript
ip(ip: string): this
```
Commit with `Destination::Cidr` of the IP as `/32` or `/128`.
Parameters
ipstring
Single IPv4 or IPv6 address.
#### destination.cidr()
```typescript
cidr(cidr: string): this
```
Commit with `Destination::Cidr`.
Parameters
cidrstring
CIDR notation.
#### destination.domain()
```typescript
domain(domain: string): this
```
Commit with `Destination::Domain`.
Parameters
domainstring
Fully qualified domain name.
#### destination.domainSuffix()
```typescript
domainSuffix(suffix: string): this
```
Commit with `Destination::DomainSuffix`.
Parameters
suffixstring
Domain suffix.
#### destination.group()
```typescript
group(group: string): this
```
Commit with `Destination::Group`. `group` is a [`DestinationGroup`](#destinationgroup) string.
Parameters
#### destination.any()
```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.
#### dns.rebindProtection()
```typescript
rebindProtection(enabled: boolean): this
```
Toggle DNS rebinding protection. When enabled, DNS responses resolving to private IPs are blocked.
Parameters
enabledboolean
Enable rebinding protection.
#### dns.nameservers()
Local-only
```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.
#### dns.queryTimeoutMs()
```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 => ...)`.
#### tls.bypass()
```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.
#### tls.verifyUpstream()
```typescript
verifyUpstream(verify: boolean): this
```
Verify upstream server certificates. Default `true`. Set to `false` only for self-signed servers.
Parameters
verifyboolean
Verify upstream certs.
#### tls.verifyUpstreamFor()
```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.
#### tls.interceptedPorts()
Local-only
```typescript
interceptedPorts(ports: number[]): this
```
TCP ports where interception is active. Default: `[443]`.
Parameters
portsnumber[]
Intercepted TCP ports.
#### tls.blockQuic()
```typescript
blockQuic(block: boolean): this
```
Block QUIC on intercepted ports, forcing TCP/TLS fallback.
Parameters
#### tls.interceptCaCert()
Local-only
```typescript
interceptCaCert(path: string): this
```
Path to a PEM file used as the intercepting CA's certificate.
Parameters
pathstring
PEM cert path.
#### tls.interceptCaKey()
Local-only
```typescript
interceptCaKey(path: string): this
```
Path to a PEM file used as the intercepting CA's private key.
Parameters
#### tls.upstreamCaCert()
```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.
#### tls.upstreamCaCertFor()
```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.
#### violation.block()
```typescript
block(): this
```
Block the request silently.
#### violation.blockAndLog()
```typescript
blockAndLog(): this
```
Block the request and emit a warning log.
#### violation.blockAndTerminate()
```typescript
blockAndTerminate(): this
```
Block the request and terminate the sandbox.
#### violation.passthroughHost()
```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
#### violation.passthroughHostPattern()
```typescript
passthroughHostPattern(pattern: string): this
```
Allow placeholders to pass through unchanged to matching wildcard hosts.
Parameters
patternstring
Wildcard host pattern.
#### violation.passthroughAllHosts()
```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.
## NetworkRateLimiterBuilder
Groups local rate limits by traffic direction. Supplied to [`NetworkBuilder.rateLimiter()`](#ratelimiter).
#### .egress()
```typescript
egress(configure: (r: RateLimiterBuilder) => RateLimiterBuilder): this
```
Configure the guest-to-runtime direction.
#### .ingress()
```typescript
ingress(configure: (r: RateLimiterBuilder) => RateLimiterBuilder): this
```
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 `this`.
Validation runs at `NetworkBuilder.build()`: a limiter with neither bucket, a zero bucket size or refill interval, or a burst without its bucket throws. Bucket values must be non-negative integers.
#### .bandwidth()
```typescript
bandwidth(sizeBytes: number, refillTimeMs: number): this
```
Cap bandwidth at `sizeBytes` bytes per `refillTimeMs` milliseconds.
Parameters
sizeBytesnumber
Bucket capacity in bytes.
refillTimeMsnumber
Time to refill the full bucket, in milliseconds.
#### .bandwidthBurst()
```typescript
bandwidthBurst(sizeBytes: number): this
```
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()`.
#### .ops()
```typescript
ops(count: number, refillTimeMs: number): this
```
Cap packet rate at `count` frames per `refillTimeMs` milliseconds.
#### .opsBurst()
```typescript
opsBurst(count: number): this
```
Grant a one-time startup burst of extra frames on top of the ops bucket. Requires `ops()`.
---
## InterfaceOverridesBuilder
Used by NetworkBuilder.interface()
Builder for per-sandbox network interface overrides.
#### interface.mac()
```typescript
.mac(mac)
```
Set the interface MAC address
#### interface.mtu()
```typescript
.mtu(mtu)
```
Set the interface MTU
#### interface.ipv4()
```typescript
.ipv4(address)
```
Pin a fixed IPv4 address
#### interface.ipv6()
```typescript
.ipv6(address)
```
Pin a fixed IPv6 address
## Types
### NetworkConfig
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 |
| rateLimiter | [`NetworkRateLimiterConfig`](#networkratelimiterconfig) ` \| null` | Local rate limits grouped by direction |
| interface | `{ ipv4Pool?, ipv6Pool?, ipv4Address?, ipv6Address?, mac?, mtu? }` | Optional interface overrides |
| trustHostCAs | `boolean` | Ship host CAs into the guest |
### NetworkProfile
Composable high-level access category accepted by [`NetworkPolicy.fromProfiles()`](#networkpolicyfromprofiles).
```typescript
type NetworkProfile = "public" | "private" | "host";
```
### Action
Used by Rule.action · NetworkPolicy defaults
Action taken on a matching rule (or the per-direction default).
```typescript
type Action = "allow" | "deny";
```
### Direction
Used by Rule.direction
Direction the rule applies to.
```typescript
type Direction = "egress" | "ingress" | "any";
```
### DestinationGroup
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
Used by Rule.protocols
Transport protocol filter. Empty `Rule.protocols` means "any protocol".
```typescript
type Protocol = "tcp" | "udp" | "icmpv4" | "icmpv6";
```
### PublishedPort
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
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
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 |
### NetworkRateLimiterConfig
Used by NetworkConfig.rateLimiter
```typescript
interface NetworkRateLimiterConfig {
readonly egress?: RateLimiterConfig;
readonly ingress?: RateLimiterConfig;
}
```
Local network rate limits grouped by direction. An omitted direction is unlimited.
### RateLimiterConfig
Held by NetworkRateLimiterConfig
```typescript
interface RateLimiterConfig {
readonly bandwidth?: TokenBucketConfig;
readonly ops?: TokenBucketConfig;
}
```
Rate limiter for one traffic direction. A missing bucket leaves that dimension unlimited.
### TokenBucketConfig
Held by RateLimiterConfig
One token bucket of a rate limiter: starts full, refills continuously at `size` tokens per `refillTimeMs`, and the one-time burst never refills.
```typescript
interface TokenBucketConfig {
readonly size: number;
readonly refillTimeMs: number;
readonly oneTimeBurst: number;
}
```