> ## Documentation Index
> Fetch the complete documentation index at: https://docs.microsandbox.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Networking

> 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.

<p className="msb-label" id="typical-flow">Typical flow</p>

```typescript theme={null}
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 theme={null}
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 theme={null}
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 theme={null}
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.

#### <span className="msb-recv">NetworkPolicy.</span><span className="msb-hn">builder()</span>

```typescript theme={null}
builder(): NetworkPolicyBuilder
```

<Accordion title="Example">
  ```typescript theme={null}
  import { NetworkPolicy } from "microsandbox";

  const policy = NetworkPolicy.builder()
    .defaultDeny()
    .egress((e) => e.tcp().port(443).allowPublic().allowPrivate())
    .build();
  ```
</Accordion>

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.

<p className="msb-label">Returns</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><a className="msb-type" href="#networkpolicybuilder">NetworkPolicyBuilder</a></div>
    <div className="msb-param-desc">Empty builder.</div>
  </div>
</div>

#### <span className="msb-recv">NetworkPolicy.</span><span className="msb-hn">none()</span>

```typescript theme={null}
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.

#### <span className="msb-recv">NetworkPolicy.</span><span className="msb-hn">allowAll()</span>

```typescript theme={null}
allowAll(): NetworkPolicy
```

Unrestricted network access: allow everything in both directions, no rules. Includes private addresses and the host machine.

#### <span className="msb-recv">NetworkPolicy.</span><span className="msb-hn">publicOnly()</span>

```typescript theme={null}
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.

#### <span className="msb-recv">NetworkPolicy.</span><span className="msb-hn">nonLocal()</span>

```typescript theme={null}
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.

#### <span className="msb-recv">Rule.</span><span className="msb-hn">allowEgress()</span>

```typescript theme={null}
allowEgress(destination: Destination): Rule
```

<Accordion title="Example">
  ```typescript theme={null}
  import { Rule, Destination } from "microsandbox";

  const r = Rule.allowEgress(Destination.domain("api.example.com"));
  ```
</Accordion>

Allow rule with direction `egress`. Empty protocols and ports mean "any".

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>destination</code><a className="msb-type" href="#destination">Destination</a></div>
    <div className="msb-param-desc">Target filter.</div>
  </div>
</div>

#### <span className="msb-recv">Rule.</span><span className="msb-hn">denyEgress()</span>

```typescript theme={null}
denyEgress(destination: Destination): Rule
```

Deny rule with direction `egress`.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>destination</code><a className="msb-type" href="#destination">Destination</a></div>
    <div className="msb-param-desc">Target filter.</div>
  </div>
</div>

#### <span className="msb-recv">Rule.</span><span className="msb-hn">allowIngress()</span>

```typescript theme={null}
allowIngress(destination: Destination): Rule
```

Allow rule with direction `ingress`.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>destination</code><a className="msb-type" href="#destination">Destination</a></div>
    <div className="msb-param-desc">Target filter.</div>
  </div>
</div>

#### <span className="msb-recv">Rule.</span><span className="msb-hn">denyIngress()</span>

```typescript theme={null}
denyIngress(destination: Destination): Rule
```

Deny rule with direction `ingress`.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>destination</code><a className="msb-type" href="#destination">Destination</a></div>
    <div className="msb-param-desc">Target filter.</div>
  </div>
</div>

#### <span className="msb-recv">Rule.</span><span className="msb-hn">allowAny()</span>

```typescript theme={null}
allowAny(destination: Destination): Rule
```

Allow rule with direction `any` (matches in either direction).

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>destination</code><a className="msb-type" href="#destination">Destination</a></div>
    <div className="msb-param-desc">Target filter.</div>
  </div>
</div>

#### <span className="msb-recv">Rule.</span><span className="msb-hn">denyAny()</span>

```typescript theme={null}
denyAny(destination: Destination): Rule
```

Deny rule with direction `any` (matches in either direction).

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>destination</code><a className="msb-type" href="#destination">Destination</a></div>
    <div className="msb-param-desc">Target filter.</div>
  </div>
</div>

#### <span className="msb-recv">Rule.</span><span className="msb-hn">allowDns()</span>

```typescript theme={null}
allowDns(): Rule
```

<Accordion title="Example">
  ```typescript theme={null}
  import { NetworkPolicy, Rule } from "microsandbox";

  const policy: NetworkPolicy = {
    defaultEgress: "deny",
    defaultIngress: "deny",
    rules: [Rule.allowDns()],
  };
  ```
</Accordion>

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).

#### <span className="msb-recv">Destination.</span><span className="msb-hn">any()</span>

```typescript theme={null}
any(): Destination
```

Match any destination.

#### <span className="msb-recv">Destination.</span><span className="msb-hn">cidr()</span>

```typescript theme={null}
cidr(cidr: string): Destination
```

Match an IP range.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>cidr</code><span className="msb-type">string</span></div>
    <div className="msb-param-desc">CIDR notation, e.g. <code>"10.0.0.0/8"</code>.</div>
  </div>
</div>

#### <span className="msb-recv">Destination.</span><span className="msb-hn">domain()</span>

```typescript theme={null}
domain(domain: string): Destination
```

Match an exact domain.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>domain</code><span className="msb-type">string</span></div>
    <div className="msb-param-desc">Fully qualified domain name.</div>
  </div>
</div>

#### <span className="msb-recv">Destination.</span><span className="msb-hn">domainSuffix()</span>

```typescript theme={null}
domainSuffix(suffix: string): Destination
```

Match the apex domain and every subdomain.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>suffix</code><span className="msb-type">string</span></div>
    <div className="msb-param-desc">Domain suffix.</div>
  </div>
</div>

#### <span className="msb-recv">Destination.</span><span className="msb-hn">group()</span>

```typescript theme={null}
group(group: DestinationGroup): Destination
```

Match a predefined address group.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>group</code><a className="msb-type" href="#destinationgroup">DestinationGroup</a></div>
    <div className="msb-param-desc">Group keyword.</div>
  </div>
</div>

#### <span className="msb-recv">PortRange.</span><span className="msb-hn">single()</span>

```typescript theme={null}
single(port: number): PortRange
```

Match a single port. `start` and `end` are set to the same value.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>port</code><span className="msb-type">number</span></div>
    <div className="msb-param-desc">Port number.</div>
  </div>
</div>

#### <span className="msb-recv">PortRange.</span><span className="msb-hn">range()</span>

```typescript theme={null}
range(start: number, end: number): PortRange
```

Match an inclusive port range.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>start</code><span className="msb-type">number</span></div>
    <div className="msb-param-desc">Lower bound (inclusive).</div>
  </div>

  <div className="msb-param">
    <div className="msb-param-key"><code>end</code><span className="msb-type">number</span></div>
    <div className="msb-param-desc">Upper bound (inclusive).</div>
  </div>
</div>

## 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.

#### <span className="msb-recv">.</span><span className="msb-hn">policy()</span>

```typescript theme={null}
policy(policy: NetworkPolicy | NetworkPolicyBuilder): this
```

<Accordion title="Example">
  ```typescript theme={null}
  import { NetworkPolicy, Sandbox } from "microsandbox";

  const sb = await Sandbox.builder("api")
    .image("python")
    .network((n) => n.policy(NetworkPolicy.publicOnly()))
    .create();
  ```
</Accordion>

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).

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>policy</code><a className="msb-type" href="#networkpolicy-2">NetworkPolicy</a></div>
    <div className="msb-param-desc">Policy literal, factory result, or builder.</div>
  </div>
</div>

#### <span className="msb-recv">.</span><span className="msb-hn">port()</span>

```typescript theme={null}
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`.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>host</code><span className="msb-type">number</span></div>
    <div className="msb-param-desc">Port on the host.</div>
  </div>

  <div className="msb-param">
    <div className="msb-param-key"><code>guest</code><span className="msb-type">number</span></div>
    <div className="msb-param-desc">Port inside the sandbox.</div>
  </div>
</div>

#### <span className="msb-recv">.</span><span className="msb-hn">portBind()</span>

```typescript theme={null}
portBind(bind: string, host: number, guest: number): this
```

Publish a TCP port on a specific host bind address, such as `0.0.0.0`.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>bind</code><span className="msb-type">string</span></div>
    <div className="msb-param-desc">Host bind address.</div>
  </div>

  <div className="msb-param">
    <div className="msb-param-key"><code>host</code><span className="msb-type">number</span></div>
    <div className="msb-param-desc">Port on the host.</div>
  </div>

  <div className="msb-param">
    <div className="msb-param-key"><code>guest</code><span className="msb-type">number</span></div>
    <div className="msb-param-desc">Port inside the sandbox.</div>
  </div>
</div>

#### <span className="msb-recv">.</span><span className="msb-hn">portUdp()</span>

```typescript theme={null}
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`.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>host</code><span className="msb-type">number</span></div>
    <div className="msb-param-desc">Port on the host.</div>
  </div>

  <div className="msb-param">
    <div className="msb-param-key"><code>guest</code><span className="msb-type">number</span></div>
    <div className="msb-param-desc">Port inside the sandbox.</div>
  </div>
</div>

#### <span className="msb-recv">.</span><span className="msb-hn">portUdpBind()</span>

```typescript theme={null}
portUdpBind(bind: string, host: number, guest: number): this
```

Publish a UDP port on a specific host bind address.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>bind</code><span className="msb-type">string</span></div>
    <div className="msb-param-desc">Host bind address.</div>
  </div>

  <div className="msb-param">
    <div className="msb-param-key"><code>host</code><span className="msb-type">number</span></div>
    <div className="msb-param-desc">Port on the host.</div>
  </div>

  <div className="msb-param">
    <div className="msb-param-key"><code>guest</code><span className="msb-type">number</span></div>
    <div className="msb-param-desc">Port inside the sandbox.</div>
  </div>
</div>

#### <span className="msb-recv">.</span><span className="msb-hn">dns()</span>

```typescript theme={null}
dns(configure: (b: DnsBuilder) => DnsBuilder): this
```

<Accordion title="Example">
  ```typescript theme={null}
  .network((n) => n.dns((d) => d.rebindProtection(true).queryTimeoutMs(2000)))
  ```
</Accordion>

Configure DNS interception. See [`DnsBuilder`](#dnsbuilder).

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>configure</code><a className="msb-type" href="#dnsbuilder">DnsBuilder</a></div>
    <div className="msb-param-desc">Configure DNS.</div>
  </div>
</div>

#### <span className="msb-recv">.</span><span className="msb-hn">tls()</span>

```typescript theme={null}
tls(configure: (b: TlsBuilder) => TlsBuilder): this
```

Configure TLS interception. See [`TlsBuilder`](#tlsbuilder).

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>configure</code><a className="msb-type" href="#tlsbuilder">TlsBuilder</a></div>
    <div className="msb-param-desc">Configure TLS.</div>
  </div>
</div>

#### <span className="msb-recv">.</span><span className="msb-hn">trustHostCAs()</span>

```typescript theme={null}
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.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>enabled</code><span className="msb-type">boolean</span></div>
    <div className="msb-param-desc">Ship host CAs into the guest.</div>
  </div>
</div>

#### <span className="msb-recv">.</span><span className="msb-hn">maxConnections()</span>

```typescript theme={null}
maxConnections(max: number): this
```

Limit the maximum number of concurrent network connections from the sandbox.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>max</code><span className="msb-type">number</span></div>
    <div className="msb-param-desc">Maximum concurrent connections.</div>
  </div>
</div>

#### <span className="msb-recv">.</span><span className="msb-hn">ipv4Pool()</span>

```typescript theme={null}
ipv4Pool(pool: string): this
```

Set the IPv4 pool used to derive per-sandbox `/30` guest subnets. Defaults to `172.16.0.0/12`.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>pool</code><span className="msb-type">string</span></div>
    <div className="msb-param-desc">IPv4 CIDR pool.</div>
  </div>
</div>

#### <span className="msb-recv">.</span><span className="msb-hn">ipv6Pool()</span>

```typescript theme={null}
ipv6Pool(pool: string): this
```

Set the IPv6 pool used to derive per-sandbox `/64` guest prefixes. Defaults to `fd42:6d73:62::/48`.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>pool</code><span className="msb-type">string</span></div>
    <div className="msb-param-desc">IPv6 CIDR pool.</div>
  </div>
</div>

#### <span className="msb-recv" id="nb-interface">.</span><span className="msb-hn">interface()</span>

```typescript theme={null}
interface(configure: (b: InterfaceOverridesBuilder) => InterfaceOverridesBuilder): this
```

<Accordion title="Example">
  ```typescript theme={null}
  .network((n) => n.interface((i) => i.mtu(1400).ipv4("172.16.0.2")))
  ```
</Accordion>

Override per-sandbox interface attributes (MAC, MTU, fixed IPv4 / IPv6 address). The [`InterfaceOverridesBuilder`](#interfaceoverridesbuilder) exposes `.mac()`, `.mtu()`, `.ipv4()`, and `.ipv6()`.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>configure</code><a className="msb-type" href="#interfaceoverridesbuilder">InterfaceOverridesBuilder</a></div>
    <div className="msb-param-desc">Configure interface overrides.</div>
  </div>
</div>

#### <span className="msb-recv">.</span><span className="msb-hn">enabled()</span>

```typescript theme={null}
enabled(enabled: boolean): this
```

Enable or disable networking entirely. When `false`, no network interface is created.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>enabled</code><span className="msb-type">boolean</span></div>
    <div className="msb-param-desc">Master enable flag.</div>
  </div>
</div>

#### <span className="msb-recv">.</span><span className="msb-hn">onSecretViolation()</span>

```typescript theme={null}
onSecretViolation(configure: (b: ViolationActionBuilder) => ViolationActionBuilder): this
```

<Accordion title="Example">
  ```typescript theme={null}
  .network((n) =>
    n.onSecretViolation((v) =>
      v.blockAndLog().passthroughHost("api.anthropic.com"),
    ),
  )
  ```
</Accordion>

Configure the action taken when a secret reaches a disallowed host. See [`ViolationActionBuilder`](#violationactionbuilder).

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>configure</code><a className="msb-type" href="#violationactionbuilder">ViolationActionBuilder</a></div>
    <div className="msb-param-desc">Configure the violation action.</div>
  </div>
</div>

Passthrough hosts receive placeholders unchanged. They do **not** receive real secret values.

#### <span className="msb-recv" id="nb-secret">.</span><span className="msb-hn">secret()</span>

```typescript theme={null}
secret(configure: (b: SecretBuilder) => SecretBuilder): this
```

Add a secret with full configuration. See [`SecretBuilder`](/sdk/typescript/secrets#secretbuilder).

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>configure</code><a className="msb-type" href="/sdk/typescript/secrets#secretbuilder">SecretBuilder</a></div>
    <div className="msb-param-desc">Configure the secret.</div>
  </div>
</div>

#### <span className="msb-recv">.</span><span className="msb-hn">secretEnv()</span>

```typescript theme={null}
secretEnv(envVar: string, value: string, placeholder: string, allowedHost: string): this
```

Four-arg explicit-placeholder shorthand for adding a secret without opening a builder callback.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>envVar</code><span className="msb-type">string</span></div>
    <div className="msb-param-desc">Environment variable name (non-empty, no <code>=</code> or NUL).</div>
  </div>

  <div className="msb-param">
    <div className="msb-param-key"><code>value</code><span className="msb-type">string</span></div>
    <div className="msb-param-desc">Real secret value.</div>
  </div>

  <div className="msb-param">
    <div className="msb-param-key"><code>placeholder</code><span className="msb-type">string</span></div>
    <div className="msb-param-desc">Placeholder string: non-empty, up to 1024 bytes, no NUL/CR/LF.</div>
  </div>

  <div className="msb-param">
    <div className="msb-param-key"><code>allowedHost</code><span className="msb-type">string</span></div>
    <div className="msb-param-desc">Single hostname allowed to receive the real value.</div>
  </div>
</div>

#### <span className="msb-recv">.</span><span className="msb-hn">secretEnvSimple()</span>

```typescript theme={null}
secretEnvSimple(envVar: string, value: string, allowedHost: string): this
```

<Accordion title="Example">
  ```typescript theme={null}
  .network((n) =>
    n.secretEnvSimple("OPENAI_API_KEY", process.env.OPENAI_API_KEY!, "api.openai.com"),
  )
  ```
</Accordion>

Three-arg auto-placeholder shorthand. Auto-generates the placeholder as `$MSB_<envVar>`, 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).

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>envVar</code><span className="msb-type">string</span></div>
    <div className="msb-param-desc">Environment variable name (non-empty, no <code>=</code> or NUL).</div>
  </div>

  <div className="msb-param">
    <div className="msb-param-key"><code>value</code><span className="msb-type">string</span></div>
    <div className="msb-param-desc">Real secret value.</div>
  </div>

  <div className="msb-param">
    <div className="msb-param-key"><code>allowedHost</code><span className="msb-type">string</span></div>
    <div className="msb-param-desc">Single hostname allowed to receive the real value.</div>
  </div>
</div>

#### <span className="msb-recv" id="nb-build">.</span><span className="msb-hn">build()</span>

```typescript theme={null}
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.

<p className="msb-label">Returns</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><a className="msb-type" href="#networkconfig">NetworkConfig</a></div>
    <div className="msb-param-desc">The materialized network configuration.</div>
  </div>
</div>

## 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 theme={null}
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();
```

#### <span className="msb-recv">.</span><span className="msb-hn">defaultDeny()</span>

```typescript theme={null}
defaultDeny(): this
```

Set both `defaultEgress` and `defaultIngress` to `"deny"`.

#### <span className="msb-recv">.</span><span className="msb-hn">defaultAllow()</span>

```typescript theme={null}
defaultAllow(): this
```

Set both `defaultEgress` and `defaultIngress` to `"allow"`.

#### <span className="msb-recv">.</span><span className="msb-hn">defaultEgress()</span>

```typescript theme={null}
defaultEgress(action: "allow" | "deny"): this
```

Per-direction override for the egress default action.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>action</code><span className="msb-type">"allow" | "deny"</span></div>
    <div className="msb-param-desc">Default action for egress.</div>
  </div>
</div>

#### <span className="msb-recv">.</span><span className="msb-hn">defaultIngress()</span>

```typescript theme={null}
defaultIngress(action: "allow" | "deny"): this
```

Per-direction override for the ingress default action.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>action</code><span className="msb-type">"allow" | "deny"</span></div>
    <div className="msb-param-desc">Default action for ingress.</div>
  </div>
</div>

#### <span className="msb-recv">.</span><span className="msb-hn">egress()</span>

```typescript theme={null}
egress(configure: (rb: RuleBuilder) => RuleBuilder): this
```

Sugar for [`rule()`](#rule) with direction pre-set to `egress`.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>configure</code><a className="msb-type" href="#rulebuilder">RuleBuilder</a></div>
    <div className="msb-param-desc">Add egress rules.</div>
  </div>
</div>

#### <span className="msb-recv">.</span><span className="msb-hn">ingress()</span>

```typescript theme={null}
ingress(configure: (rb: RuleBuilder) => RuleBuilder): this
```

Sugar for [`rule()`](#rule) with direction pre-set to `ingress`.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>configure</code><a className="msb-type" href="#rulebuilder">RuleBuilder</a></div>
    <div className="msb-param-desc">Add ingress rules.</div>
  </div>
</div>

#### <span className="msb-recv">.</span><span className="msb-hn">any()</span>

```typescript theme={null}
any(configure: (rb: RuleBuilder) => RuleBuilder): this
```

Sugar for [`rule()`](#rule) with direction pre-set to `any`. Rules committed inside apply in both directions.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>configure</code><a className="msb-type" href="#rulebuilder">RuleBuilder</a></div>
    <div className="msb-param-desc">Add bidirectional rules.</div>
  </div>
</div>

#### <span className="msb-recv">.</span><span className="msb-hn">rule()</span>

```typescript theme={null}
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.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>configure</code><a className="msb-type" href="#rulebuilder">RuleBuilder</a></div>
    <div className="msb-param-desc">Add rules; set direction first.</div>
  </div>
</div>

#### <span className="msb-recv">.</span><span className="msb-hn">build()</span>

```typescript theme={null}
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.

<p className="msb-label">Returns</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><a className="msb-type" href="#networkpolicy-2">NetworkPolicy</a></div>
    <div className="msb-param-desc">The materialized policy.</div>
  </div>
</div>

## 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 theme={null}
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.

#### <span className="msb-recv" id="rb-egress">.</span><span className="msb-hn">egress()</span>

```typescript theme={null}
egress(): this
```

Set direction to `egress` for subsequent rule-adders.

#### <span className="msb-recv" id="rb-ingress">.</span><span className="msb-hn">ingress()</span>

```typescript theme={null}
ingress(): this
```

Set direction to `ingress` for subsequent rule-adders.

#### <span className="msb-recv" id="rb-any">.</span><span className="msb-hn">any()</span>

```typescript theme={null}
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.

#### <span className="msb-recv">.</span><span className="msb-hn">tcp()</span>

```typescript theme={null}
tcp(): this
```

Add `tcp` to the protocols set.

#### <span className="msb-recv">.</span><span className="msb-hn">udp()</span>

```typescript theme={null}
udp(): this
```

Add `udp` to the protocols set.

#### <span className="msb-recv">.</span><span className="msb-hn">icmpv4()</span>

```typescript theme={null}
icmpv4(): this
```

Add `icmpv4` to the protocols set. Egress-only; an ICMP rule on an `ingress` or `any` direction fails build.

#### <span className="msb-recv">.</span><span className="msb-hn">icmpv6()</span>

```typescript theme={null}
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).

#### <span className="msb-recv" id="port-1">.</span><span className="msb-hn">port()</span>

```typescript theme={null}
port(port: number): this
```

Add a single port to the ports set.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>port</code><span className="msb-type">number</span></div>
    <div className="msb-param-desc">Port number <code>0..=65535</code>.</div>
  </div>
</div>

#### <span className="msb-recv">.</span><span className="msb-hn">portRange()</span>

```typescript theme={null}
portRange(lo: number, hi: number): this
```

Add an inclusive port range. `lo > hi` records an error surfaced at [`build()`](#build) time.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>lo</code><span className="msb-type">number</span></div>
    <div className="msb-param-desc">Lower bound (inclusive).</div>
  </div>

  <div className="msb-param">
    <div className="msb-param-key"><code>hi</code><span className="msb-type">number</span></div>
    <div className="msb-param-desc">Upper bound (inclusive).</div>
  </div>
</div>

#### <span className="msb-recv">.</span><span className="msb-hn">ports()</span>

```typescript theme={null}
ports(ports: number[]): this
```

Add multiple single ports. Equivalent to calling [`port()`](#port-1) once per element.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>ports</code><span className="msb-type">number\[]</span></div>
    <div className="msb-param-desc">Port numbers.</div>
  </div>
</div>

### Group rule-adders

Each adder commits one rule using the current state and the named destination group.

#### <span className="msb-recv">.</span><span className="msb-hn">allowPublic()</span>

```typescript theme={null}
allowPublic(): this
```

Allow the `public` group (complement of named categories: every IP not in any other group).

#### <span className="msb-recv">.</span><span className="msb-hn">denyPublic()</span>

```typescript theme={null}
denyPublic(): this
```

Deny the `public` group.

#### <span className="msb-recv">.</span><span className="msb-hn">allowPrivate()</span>

```typescript theme={null}
allowPrivate(): this
```

Allow the `private` group (RFC1918 + ULA + CGN).

#### <span className="msb-recv">.</span><span className="msb-hn">denyPrivate()</span>

```typescript theme={null}
denyPrivate(): this
```

Deny the `private` group.

#### <span className="msb-recv">.</span><span className="msb-hn">allowLoopback()</span>

```typescript theme={null}
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).

#### <span className="msb-recv">.</span><span className="msb-hn">denyLoopback()</span>

```typescript theme={null}
denyLoopback(): this
```

Deny the `loopback` group.

#### <span className="msb-recv">.</span><span className="msb-hn">allowLinkLocal()</span>

```typescript theme={null}
allowLinkLocal(): this
```

Allow the `link-local` group (`169.254.0.0/16`, `fe80::/10`). Excludes the metadata IP `169.254.169.254`.

#### <span className="msb-recv">.</span><span className="msb-hn">denyLinkLocal()</span>

```typescript theme={null}
denyLinkLocal(): this
```

Deny the `link-local` group.

#### <span className="msb-recv">.</span><span className="msb-hn">allowMeta()</span>

```typescript theme={null}
allowMeta(): this
```

Allow the `metadata` group (`169.254.169.254`). **Dangerous on cloud hosts** (exposes IAM credentials).

#### <span className="msb-recv">.</span><span className="msb-hn">denyMeta()</span>

```typescript theme={null}
denyMeta(): this
```

Deny the `metadata` group.

#### <span className="msb-recv">.</span><span className="msb-hn">allowMulticast()</span>

```typescript theme={null}
allowMulticast(): this
```

Allow the `multicast` group (`224.0.0.0/4`, `ff00::/8`).

#### <span className="msb-recv">.</span><span className="msb-hn">denyMulticast()</span>

```typescript theme={null}
denyMulticast(): this
```

Deny the `multicast` group.

#### <span className="msb-recv">.</span><span className="msb-hn">allowHost()</span>

```typescript theme={null}
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).

#### <span className="msb-recv">.</span><span className="msb-hn">denyHost()</span>

```typescript theme={null}
denyHost(): this
```

Deny the `host` group.

### Composite rule-adders

#### <span className="msb-recv">.</span><span className="msb-hn">allowLocal()</span>

```typescript theme={null}
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.

#### <span className="msb-recv">.</span><span className="msb-hn">denyLocal()</span>

```typescript theme={null}
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.

#### <span className="msb-recv">.</span><span className="msb-hn">allowDomain()</span>

```typescript theme={null}
allowDomain(name: string): this
```

Add one `Destination::Domain` allow rule.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>name</code><span className="msb-type">string</span></div>
    <div className="msb-param-desc">Fully qualified domain name.</div>
  </div>
</div>

#### <span className="msb-recv">.</span><span className="msb-hn">denyDomain()</span>

```typescript theme={null}
denyDomain(name: string): this
```

Add one `Destination::Domain` deny rule.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>name</code><span className="msb-type">string</span></div>
    <div className="msb-param-desc">Fully qualified domain name.</div>
  </div>
</div>

#### <span className="msb-recv">.</span><span className="msb-hn">allowDomains()</span>

```typescript theme={null}
allowDomains(names: string[]): this
```

Add one `Destination::Domain` allow rule per name.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>names</code><span className="msb-type">string\[]</span></div>
    <div className="msb-param-desc">Fully qualified domain names.</div>
  </div>
</div>

#### <span className="msb-recv">.</span><span className="msb-hn">denyDomains()</span>

```typescript theme={null}
denyDomains(names: string[]): this
```

Add one `Destination::Domain` deny rule per name.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>names</code><span className="msb-type">string\[]</span></div>
    <div className="msb-param-desc">Fully qualified domain names.</div>
  </div>
</div>

#### <span className="msb-recv">.</span><span className="msb-hn">allowDomainSuffix()</span>

```typescript theme={null}
allowDomainSuffix(suffix: string): this
```

Add one `Destination::DomainSuffix` allow rule. Matches the apex and any subdomain.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>suffix</code><span className="msb-type">string</span></div>
    <div className="msb-param-desc">Domain suffix.</div>
  </div>
</div>

#### <span className="msb-recv">.</span><span className="msb-hn">denyDomainSuffix()</span>

```typescript theme={null}
denyDomainSuffix(suffix: string): this
```

Add one `Destination::DomainSuffix` deny rule. Matches the apex and any subdomain.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>suffix</code><span className="msb-type">string</span></div>
    <div className="msb-param-desc">Domain suffix.</div>
  </div>
</div>

#### <span className="msb-recv">.</span><span className="msb-hn">allowDomainSuffixes()</span>

```typescript theme={null}
allowDomainSuffixes(suffixes: string[]): this
```

Add one `Destination::DomainSuffix` allow rule per suffix.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>suffixes</code><span className="msb-type">string\[]</span></div>
    <div className="msb-param-desc">Domain suffixes.</div>
  </div>
</div>

#### <span className="msb-recv">.</span><span className="msb-hn">denyDomainSuffixes()</span>

```typescript theme={null}
denyDomainSuffixes(suffixes: string[]): this
```

Add one `Destination::DomainSuffix` deny rule per suffix.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>suffixes</code><span className="msb-type">string\[]</span></div>
    <div className="msb-param-desc">Domain suffixes.</div>
  </div>
</div>

### Explicit-destination rule-adders

`.allow()` / `.deny()` open a [`RuleDestinationBuilder`](#ruledestinationbuilder) callback. Exactly one destination call commits the rule.

```typescript theme={null}
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();
```

#### <span className="msb-recv" id="rb-allow">.</span><span className="msb-hn">allow()</span>

```typescript theme={null}
allow(configure: (d: RuleDestinationBuilder) => RuleDestinationBuilder): this
```

Begin an explicit-destination rule with action `allow`.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>configure</code><a className="msb-type" href="#ruledestinationbuilder">RuleDestinationBuilder</a></div>
    <div className="msb-param-desc">Commit exactly one destination.</div>
  </div>
</div>

#### <span className="msb-recv" id="rb-deny">.</span><span className="msb-hn">deny()</span>

```typescript theme={null}
deny(configure: (d: RuleDestinationBuilder) => RuleDestinationBuilder): this
```

Begin an explicit-destination rule with action `deny`.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>configure</code><a className="msb-type" href="#ruledestinationbuilder">RuleDestinationBuilder</a></div>
    <div className="msb-param-desc">Commit exactly one destination.</div>
  </div>
</div>

## RuleDestinationBuilder

Returned by [`RuleBuilder`](#rulebuilder)`.allow(d => ...)` / `.deny(d => ...)`. Exactly one destination call commits the rule; dropping without a destination call silently does nothing.

#### <span className="msb-recv" id="rd-ip">.</span><span className="msb-hn">ip()</span>

```typescript theme={null}
ip(ip: string): this
```

Commit with `Destination::Cidr` of the IP as `/32` or `/128`.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>ip</code><span className="msb-type">string</span></div>
    <div className="msb-param-desc">Single IPv4 or IPv6 address.</div>
  </div>
</div>

#### <span className="msb-recv" id="rd-cidr">.</span><span className="msb-hn">cidr()</span>

```typescript theme={null}
cidr(cidr: string): this
```

Commit with `Destination::Cidr`.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>cidr</code><span className="msb-type">string</span></div>
    <div className="msb-param-desc">CIDR notation.</div>
  </div>
</div>

#### <span className="msb-recv" id="rd-domain">.</span><span className="msb-hn">domain()</span>

```typescript theme={null}
domain(domain: string): this
```

Commit with `Destination::Domain`.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>domain</code><span className="msb-type">string</span></div>
    <div className="msb-param-desc">Fully qualified domain name.</div>
  </div>
</div>

#### <span className="msb-recv" id="rd-domainsuffix">.</span><span className="msb-hn">domainSuffix()</span>

```typescript theme={null}
domainSuffix(suffix: string): this
```

Commit with `Destination::DomainSuffix`.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>suffix</code><span className="msb-type">string</span></div>
    <div className="msb-param-desc">Domain suffix.</div>
  </div>
</div>

#### <span className="msb-recv" id="rd-group">.</span><span className="msb-hn">group()</span>

```typescript theme={null}
group(group: string): this
```

Commit with `Destination::Group`. `group` is a [`DestinationGroup`](#destinationgroup) string.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>group</code><a className="msb-type" href="#destinationgroup">DestinationGroup</a></div>
    <div className="msb-param-desc">Group keyword.</div>
  </div>
</div>

#### <span className="msb-recv" id="rd-any">.</span><span className="msb-hn">any()</span>

```typescript theme={null}
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.

#### <span className="msb-recv">.</span><span className="msb-hn">rebindProtection()</span>

```typescript theme={null}
rebindProtection(enabled: boolean): this
```

Toggle DNS rebinding protection. When enabled, DNS responses resolving to private IPs are blocked.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>enabled</code><span className="msb-type">boolean</span></div>
    <div className="msb-param-desc">Enable rebinding protection.</div>
  </div>
</div>

#### <span className="msb-recv">.</span><span className="msb-hn">nameservers()</span>

```typescript theme={null}
nameservers(servers: string[]): this
```

Override upstream nameservers. Replaces any previously-set nameservers.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>servers</code><span className="msb-type">string\[]</span></div>
    <div className="msb-param-desc">Each entry is <code>IP</code>, <code>IP:PORT</code>, <code>HOST</code>, or <code>HOST:PORT</code>.</div>
  </div>
</div>

#### <span className="msb-recv">.</span><span className="msb-hn">queryTimeoutMs()</span>

```typescript theme={null}
queryTimeoutMs(ms: number): this
```

Per-DNS-query timeout in milliseconds.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>ms</code><span className="msb-type">number</span></div>
    <div className="msb-param-desc">Timeout in milliseconds.</div>
  </div>
</div>

## TlsBuilder

Builder for TLS interception settings. Used in `NetworkBuilder.tls(t => ...)`.

#### <span className="msb-recv">.</span><span className="msb-hn">bypass()</span>

```typescript theme={null}
bypass(pattern: string): this
```

Skip TLS interception for hosts matching this glob (e.g. `"*.internal.corp"`). Use for domains with certificate pinning.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>pattern</code><span className="msb-type">string</span></div>
    <div className="msb-param-desc">Glob pattern.</div>
  </div>
</div>

#### <span className="msb-recv">.</span><span className="msb-hn">verifyUpstream()</span>

```typescript theme={null}
verifyUpstream(verify: boolean): this
```

Verify upstream server certificates. Default `true`. Set to `false` only for self-signed servers.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>verify</code><span className="msb-type">boolean</span></div>
    <div className="msb-param-desc">Verify upstream certs.</div>
  </div>
</div>

#### <span className="msb-recv">.</span><span className="msb-hn">interceptedPorts()</span>

```typescript theme={null}
interceptedPorts(ports: number[]): this
```

TCP ports where interception is active. Default: `[443]`.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>ports</code><span className="msb-type">number\[]</span></div>
    <div className="msb-param-desc">Intercepted TCP ports.</div>
  </div>
</div>

#### <span className="msb-recv">.</span><span className="msb-hn">blockQuic()</span>

```typescript theme={null}
blockQuic(block: boolean): this
```

Block QUIC on intercepted ports, forcing TCP/TLS fallback.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>block</code><span className="msb-type">boolean</span></div>
    <div className="msb-param-desc">Block QUIC.</div>
  </div>
</div>

#### <span className="msb-recv">.</span><span className="msb-hn">interceptCaCert()</span>

```typescript theme={null}
interceptCaCert(path: string): this
```

Path to a PEM file used as the intercepting CA's certificate.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>path</code><span className="msb-type">string</span></div>
    <div className="msb-param-desc">PEM cert path.</div>
  </div>
</div>

#### <span className="msb-recv">.</span><span className="msb-hn">interceptCaKey()</span>

```typescript theme={null}
interceptCaKey(path: string): this
```

Path to a PEM file used as the intercepting CA's private key.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>path</code><span className="msb-type">string</span></div>
    <div className="msb-param-desc">PEM key path.</div>
  </div>
</div>

#### <span className="msb-recv">.</span><span className="msb-hn">upstreamCaCert()</span>

```typescript theme={null}
upstreamCaCert(path: string): this
```

Path to a PEM file with extra root CAs the proxy should trust.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>path</code><span className="msb-type">string</span></div>
    <div className="msb-param-desc">PEM cert path.</div>
  </div>
</div>

## 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.

#### <span className="msb-recv" id="va-block">.</span><span className="msb-hn">block()</span>

```typescript theme={null}
block(): this
```

Block the request silently.

#### <span className="msb-recv">.</span><span className="msb-hn">blockAndLog()</span>

```typescript theme={null}
blockAndLog(): this
```

Block the request and emit a warning log.

#### <span className="msb-recv">.</span><span className="msb-hn">blockAndTerminate()</span>

```typescript theme={null}
blockAndTerminate(): this
```

Block the request and terminate the sandbox.

#### <span className="msb-recv">.</span><span className="msb-hn">passthroughHost()</span>

```typescript theme={null}
passthroughHost(host: string): this
```

Allow placeholders to pass through unchanged to an exact host. The host receives the placeholder, not the real secret value.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>host</code><span className="msb-type">string</span></div>
    <div className="msb-param-desc">Exact host.</div>
  </div>
</div>

#### <span className="msb-recv">.</span><span className="msb-hn">passthroughHostPattern()</span>

```typescript theme={null}
passthroughHostPattern(pattern: string): this
```

Allow placeholders to pass through unchanged to matching wildcard hosts.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>pattern</code><span className="msb-type">string</span></div>
    <div className="msb-param-desc">Wildcard host pattern.</div>
  </div>
</div>

#### <span className="msb-recv">.</span><span className="msb-hn">passthroughAllHosts()</span>

```typescript theme={null}
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.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>iUnderstand</code><span className="msb-type">boolean</span></div>
    <div className="msb-param-desc">Must be <code>true</code> to opt in.</div>
  </div>
</div>

## Types

### NetworkConfig

<p className="msb-backref">Returned by <a href="#nb-build">NetworkBuilder.build()</a></p>

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

<p className="msb-backref">Used by <a href="#policy">NetworkBuilder.policy()</a> · returned by <a href="#networkpolicy">NetworkPolicy factories</a></p>

Ordered rule list with per-direction defaults. First-match-wins is evaluated independently for egress and ingress.

```typescript theme={null}
interface NetworkPolicy {
  readonly defaultEgress: Action;
  readonly defaultIngress: Action;
  readonly rules: readonly Rule[];
}
```

### Rule

<p className="msb-backref">Used by <a href="#networkpolicy-2">NetworkPolicy.rules</a> · built via <a href="#rule-allowegress">Rule factories</a></p>

A single ordered policy rule.

```typescript theme={null}
interface Rule {
  readonly direction: Direction;
  readonly destination: Destination;
  readonly protocols: readonly Protocol[]; // empty = any
  readonly ports: readonly PortRange[];    // empty = any
  readonly action: Action;
}
```

### Action

<p className="msb-backref">Used by <a href="#rule-2">Rule.action</a> · <a href="#networkpolicy-2">NetworkPolicy defaults</a></p>

Action taken on a matching rule (or the per-direction default).

```typescript theme={null}
type Action = "allow" | "deny";
```

### Direction

<p className="msb-backref">Used by <a href="#rule-2">Rule.direction</a></p>

Direction the rule applies to.

```typescript theme={null}
type Direction = "egress" | "ingress" | "any";
```

### Destination

<p className="msb-backref">Used by <a href="#rule-2">Rule.destination</a> · built via <a href="#destination-any">Destination factories</a></p>

Destination filter. An internally-tagged union; use the [`Destination`](#destination) factory for constructors.

```typescript theme={null}
type Destination =
  | { kind: "any" }
  | { kind: "cidr"; cidr: string }
  | { kind: "domain"; domain: string }
  | { kind: "domainSuffix"; suffix: string }
  | { kind: "group"; group: DestinationGroup };
```

### DestinationGroup

<p className="msb-backref">Used by <a href="#destinationgroup">Destination.group()</a> · <a href="#rd-group">RuleDestinationBuilder.group()</a></p>

Predefined address group keyword. The runtime constant `DestinationGroups` lists all values.

```typescript theme={null}
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

<p className="msb-backref">Used by <a href="#rule-2">Rule.protocols</a></p>

Transport protocol filter. Empty `Rule.protocols` means "any protocol".

```typescript theme={null}
type Protocol = "tcp" | "udp" | "icmpv4" | "icmpv6";
```

### PortRange

<p className="msb-backref">Used by <a href="#rule-2">Rule.ports</a> · built via <a href="#portrange-single">PortRange factories</a></p>

Inclusive port range. Always interpreted as the guest-side port.

```typescript theme={null}
interface PortRange {
  readonly start: number;
  readonly end: number;
}
```

### PublishedPort

<p className="msb-backref">Used by <a href="#networkconfig">NetworkConfig.ports</a></p>

A published port mapping from the guest to the host.

```typescript theme={null}
interface PublishedPort {
  readonly hostPort: number;
  readonly guestPort: number;
  readonly protocol: "tcp" | "udp";
  readonly hostBind: string;
}
```

### DnsConfig

<p className="msb-backref">Used by <a href="#networkconfig">NetworkConfig.dns</a></p>

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

<p className="msb-backref">Used by <a href="#networkconfig">NetworkConfig.tls</a></p>

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 |
| interceptCaCertPath | `string \| null`    | Custom intercept CA cert (PEM)              |
| interceptCaKeyPath  | `string \| null`    | Custom intercept CA key (PEM)               |

### InterfaceOverridesBuilder

<p className="msb-backref">Used by <a href="#nb-interface">NetworkBuilder.interface()</a></p>

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      |