Networking

TypeScript SDK - Network API reference

See Networking for conceptual overview and TLS Interception for TLS proxy details.

Network configuration is attached to a sandbox via SandboxBuilder.network(n => ...). Inside the callback you get a NetworkBuilder which exposes DNS, TLS, secret, and policy configuration.

import { Sandbox, NetworkPolicy } from "microsandbox";

await using sb = await Sandbox.builder("filtered")
  .image("alpine")
  .network((n) => n
    .policy(NetworkPolicy.publicOnly())
    .denyDomainSuffixes(".evil.com")
    .tls((t) => t.bypass("*.googleapis.com")),
  )
  .create();

For port publishing, use SandboxBuilder.port(host, guest) / portUdp(host, guest) (or the equivalent methods on NetworkBuilder).

NetworkPolicy

Static factory for creating preset policies. Each helper returns a plain NetworkPolicy value that can be passed to NetworkBuilder.policy(...).

import { NetworkPolicy, Rule, Destination } from "microsandbox";

// Custom policy
const custom = {
  defaultEgress: "deny",
  defaultIngress: "allow",
  rules: [
    Rule.allowEgress(Destination.domain("api.openai.com")),
    Rule.denyEgress(Destination.group("metadata")),
  ],
};

---

NetworkPolicy.allowAll()

static allowAll(): NetworkPolicy

Unrestricted network access, including to private addresses and the host machine.

---

NetworkPolicy.none()

static none(): NetworkPolicy

Deny all traffic. The guest is fully offline. exec and fs still work since they use the host-guest channel, not the network.

---

NetworkPolicy.publicOnly()

static publicOnly(): NetworkPolicy

Block private address ranges and cloud metadata endpoints. Allow everything else. This is the default policy.

---

NetworkPolicy.nonLocal()

static nonLocal(): NetworkPolicy

Allow egress to public + private (LAN) destinations; ingress allowed by default.

---

Rules and destinations

Rule

Factory for individual policy rules. Each method returns a single Rule value.

Method	Direction	Action
Rule.allowEgress(dest)	egress	allow
Rule.denyEgress(dest)	egress	deny
Rule.allowIngress(dest)	ingress	allow
Rule.denyIngress(dest)	ingress	deny
Rule.allowAny(dest)	any	allow
Rule.denyAny(dest)	any	deny

Destination

Factory for rule destinations.

Method	Description
Destination.any()	Match any destination
Destination.cidr(cidr)	Match an IP range, e.g. "10.0.0.0/8"
Destination.domain(domain)	Exact domain match
Destination.domainSuffix(suffix)	Match the apex and every subdomain
Destination.group(group)	Match a DestinationGroup

PortRange

Method	Description
PortRange.single(port)	Single port ({ start, end } set to the same value)
PortRange.range(start, end)	Inclusive port range

---

NetworkBuilder

Returned to the callback you pass to SandboxBuilder.network(...). Every setter returns the same builder.

Method	Description
enabled(b)	Enable or disable networking.
port(host, guest)	Publish a TCP port.
portUdp(host, guest)	Publish a UDP port.
policy(NetworkPolicy)	Set the policy. Use a NetworkPolicy factory or a literal.
denyDomains(...names)	Deny egress to these exact domains. Each entry adds a deny Domain("...") policy rule that fires at DNS resolution (REFUSED), TLS first-flight (SNI), and TCP egress (cache fallback). Prepended onto the policy.
denyDomainSuffixes(...suffixes)	Deny egress to all subdomains of these suffixes. Same enforcement layers.
dns(d => ...)	Configure DNS — see DnsBuilder.
tls(t => ...)	Configure TLS — see TlsBuilder.
secret(s => ...)	Add a secret — see SecretBuilder.
secretEnv(envVar, value, placeholder, allowedHost)	Four-arg explicit-placeholder shorthand.
onSecretViolation(action)	Action on disallowed secret use — see ViolationAction.
maxConnections(n)	Maximum concurrent connections.
trustHostCAs(enabled)	Ship the host’s trusted root CAs into the guest at boot. Opt-in.
build()	Internal — produce a NetworkConfig.

---

DnsBuilder

Method	Description
nameservers(servers)	Override upstream nameservers (IP, IP:PORT, HOST, or HOST:PORT).
rebindProtection(enabled)	Toggle DNS rebinding protection.
queryTimeoutMs(ms)	Per-query timeout.
build()	Internal — produce a DnsConfig.

---

TlsBuilder

Method	Description
bypass(pattern)	Skip interception for hosts matching this glob (e.g. "*.internal.corp").
verifyUpstream(verify)	Verify upstream server certificates. Default true.
interceptedPorts(ports)	TCP ports to intercept. Default [443].
blockQuic(block)	Block QUIC on intercepted ports, forcing TCP/TLS fallback.
upstreamCaCert(path)	Add a PEM file with extra root CAs the proxy should trust.
interceptCaCert(path)	PEM file used as the intercepting CA’s certificate.
interceptCaKey(path)	PEM file used as the intercepting CA’s private key.
build()	Internal — produce a TlsConfig.

---

Types

NetworkConfig

Built network configuration produced by NetworkBuilder.build().

Field	Type	Description
enabled	boolean	Master enable flag
ports	readonly PublishedPort[]	Port publishings
policy	NetworkPolicy | null	Active policy
dns	DnsConfig | null	DNS interception
tls	TlsConfig | null	TLS interception
secrets	readonly SecretEntry[]	Secret entries
secretViolation	ViolationAction | null	Action on disallowed secret use
maxConnections	number | null	Maximum concurrent connections
trustHostCAs	boolean	Ship host CAs into the guest

NetworkPolicy

interface NetworkPolicy {
  readonly defaultEgress: Action;
  readonly defaultIngress: Action;
  readonly rules: readonly Rule[];
}

Rule

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

Destination

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

Action

type Action = "allow" | "deny";

Direction

type Direction = "egress" | "ingress" | "any";

Protocol

type Protocol = "tcp" | "udp" | "icmpv4" | "icmpv6";

DestinationGroup

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
'link-local'	169.254.0.0/16 / fe80::/10
'metadata'	Cloud metadata endpoints (169.254.169.254, fd00:ec2::254)
'multicast'	Multicast addresses
'host'	The host machine, reached via host.microsandbox.internal

PortRange

interface PortRange {
  readonly start: number;
  readonly end: number;
}

DnsConfig

Field	Type	Description
nameservers	readonly string[]	Upstream nameservers
rebindProtection	boolean | null	DNS rebinding protection toggle
queryTimeoutMs	number | null	Per-query timeout

TlsConfig

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)

PublishedPort

interface PublishedPort {
  readonly hostPort: number;
  readonly guestPort: number;
  readonly protocol: "tcp" | "udp";
}