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.
See Networking for the conceptual overview and TLS Interception for TLS proxy details.
The Go SDK’s network surface is a single NetworkConfig struct passed via WithNetwork. Common shapes come from NetworkPolicy; custom rule sets are built by populating NetworkConfig.Rules directly.
sb, err := m.CreateSandbox(ctx, "worker",
m.WithImage("alpine"),
m.WithNetwork(m.NetworkPolicy.PublicOnly()),
)
NetworkPolicy
Helpers that return common preset *NetworkConfig values. Access via the package-level NetworkPolicy value.
NetworkPolicy.PublicOnly()
func (networkPolicyFactory) PublicOnly() *NetworkConfig
NetworkPolicy.None()
func (networkPolicyFactory) None() *NetworkConfig
Exec and FS still work — they use the host-guest channel, not the network.
NetworkPolicy.AllowAll()
func (networkPolicyFactory) AllowAll() *NetworkConfig
NetworkPolicy.NonLocal()
func (networkPolicyFactory) NonLocal() *NetworkConfig
Custom rules
Build a custom firewall by populating NetworkConfig.Rules. Rules are evaluated first-match-wins per direction. DefaultEgress and DefaultIngress set the fall-through action.
sb, err := m.CreateSandbox(ctx, "agent",
m.WithImage("python:3.12"),
m.WithNetwork(&m.NetworkConfig{
DefaultEgress: m.PolicyActionDeny,
DefaultIngress: m.PolicyActionAllow,
Rules: []m.PolicyRule{
{
Action: m.PolicyActionAllow,
Direction: m.PolicyDirectionEgress,
Destination: "api.openai.com",
Protocol: m.PolicyProtocolTCP,
Port: "443",
},
{
Action: m.PolicyActionAllow,
Direction: m.PolicyDirectionEgress,
Destination: ".internal",
Protocols: []m.PolicyProtocol{m.PolicyProtocolTCP},
Ports: []string{"8000-9000"},
},
},
}),
)
Rule order matters
The first matching rule wins, so a broad rule placed before a narrow one swallows it:
Rules: []m.PolicyRule{
{Action: m.PolicyActionAllow, Destination: "10.0.0.0/8"}, // matches everything in 10.x
{Action: m.PolicyActionDeny, Destination: "10.0.0.5"}, // never reached
},
Types
NetworkConfig
The configuration struct passed via WithNetwork.
| Field | Type | Description |
|---|
| Policy | NetworkPolicyPreset | Preset name. Mutually exclusive with Rules for canned configurations; set via NetworkPolicy |
| Rules | []PolicyRule | Ordered custom rules (first match wins) |
| DefaultEgress | PolicyAction | Fall-through action for outbound when no rule matches. Defaults to "deny" |
| DefaultIngress | PolicyAction | Fall-through action for inbound when no rule matches. Defaults to "allow" |
| DenyDomains | []string | Exact-match domains to refuse DNS resolution for. Adds high-priority deny Domain("...") policy rules that fire at DNS (REFUSED), TLS first-flight (SNI), and TCP egress (cache fallback) |
| DenyDomainSuffixes | []string | Domain suffixes (e.g. .ads) — denies the apex and any subdomain |
| DNS | *DNSConfig | DNS interception settings |
| DNSRebindProtection | *bool | Legacy convenience for DNS.RebindProtection. When DNS is also set, the nested value wins |
| TLS | *TLSConfig | TLS interception settings |
| Ports | map[uint16]uint16 | Host→guest TCP port mappings |
| MaxConnections | *uint | Cap concurrent network connections from the sandbox |
| OnSecretViolation | ViolationAction | Sandbox-wide action when a secret is sent to a disallowed host |
| TrustHostCAs | *bool | Ship the host’s trusted root CAs into the guest at boot. Opt-in for corporate MITM proxies (Cloudflare Warp Zero Trust, Zscaler, Netskope, …) whose gateway CA is unknown to the guest’s stock Mozilla bundle |
PolicyRule
A single firewall rule.
| Field | Type | Description |
|---|
| Action | PolicyAction | allow or deny |
| Direction | PolicyDirection | Direction this rule considers. PolicyDirectionAny matches in either |
| Destination | string | Target filter: a destination group, domain, domain suffix (prefixed with .), CIDR (10.0.0.0/8), exact IP, or "*". Domain and suffix strings are validated at sandbox creation |
| Protocol | PolicyProtocol | Legacy single-protocol field. Prefer Protocols when matching multiple |
| Protocols | []PolicyProtocol | Protocol set. Empty means any |
| Port | string | Single port ("443") or range ("8000-9000") |
| Ports | []string | Multiple port values at once |
PolicyDirectionEgress for ICMP allow/deny.
DNSConfig
type DNSConfig struct {
RebindProtection *bool
Nameservers []string
QueryTimeoutMs *uint64
}
| Field | Type | Description |
|---|
| RebindProtection | *bool | Block DNS responses resolving to private IPs. Default true when unset |
| Nameservers | []string | Upstream resolvers. Each entry is IP, IP:PORT, HOST, or HOST:PORT. Replaces /etc/resolv.conf when non-empty |
| QueryTimeoutMs | *uint64 | Per-DNS-query timeout in milliseconds |
TLSConfig
type TLSConfig struct {
Bypass []string
VerifyUpstream *bool
InterceptedPorts []uint16
BlockQUIC *bool
CACert string
CAKey string
UpstreamCACerts []string
}
| Field | Type | Description |
|---|
| Bypass | []string | Domains to skip interception (supports *.suffix globs). Use for domains with certificate pinning |
| VerifyUpstream | *bool | Verify upstream server certificates. Default true. Set false only for self-signed servers |
| InterceptedPorts | []uint16 | TCP ports where TLS interception is active. Default [443] |
| BlockQUIC | *bool | Block QUIC/HTTP3 (UDP) on intercepted ports, forcing TCP/TLS fallback |
| CACert | string | Path to a custom interception CA certificate PEM file |
| CAKey | string | Path to a custom interception CA private key PEM file |
| UpstreamCACerts | []string | Paths to additional CA bundles trusted for upstream verification |
sb, err := m.CreateSandbox(ctx, "inspect",
m.WithImage("python:3.12"),
m.WithNetwork(&m.NetworkConfig{
TLS: &m.TLSConfig{
Bypass: []string{"*.googleapis.com"},
InterceptedPorts: []uint16{443},
},
}),
)
PolicyAction
| Constant | Value | Description |
|---|
PolicyActionAllow | "allow" | Permit the traffic |
PolicyActionDeny | "deny" | Drop the traffic silently |
PolicyDirection
type PolicyDirection string
| Constant | Value | Description |
|---|
PolicyDirectionEgress | "egress" | Traffic leaving the sandbox |
PolicyDirectionIngress | "ingress" | Traffic entering the sandbox |
PolicyDirectionAny | "any" | Rule applies in either direction |
PolicyProtocol
type PolicyProtocol string
| Constant | Value | Description |
|---|
PolicyProtocolTCP | "tcp" | TCP traffic |
PolicyProtocolUDP | "udp" | UDP traffic |
PolicyProtocolICMPv4 | "icmpv4" | ICMPv4 traffic (egress only) |
PolicyProtocolICMPv6 | "icmpv6" | ICMPv6 traffic (egress only) |
NetworkPolicyPreset
type NetworkPolicyPreset string
NetworkConfig.Policy. Prefer NetworkPolicy, which returns a preconfigured *NetworkConfig.
| Constant | Value | Description |
|---|
NetworkPolicyPresetNone | "none" | Fully airgapped |
NetworkPolicyPresetPublicOnly | "public-only" | Block private + metadata; allow everything else |
NetworkPolicyPresetAllowAll | "allow-all" | Unrestricted |
NetworkPolicyPresetNonLocal | "non-local" | Public + private/LAN egress; block loopback / link-local / metadata |
Destination groups
The Destination field on PolicyRule accepts these well-known group names alongside literal CIDRs and domains:
| Value | Description |
|---|
"public" | Complement of the named categories: every address not in any other group |
"private" | Private/RFC 1918 addresses + ULA + CGN (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 100.64.0.0/10, fc00::/7) |
"loopback" | Loopback addresses (127.0.0.0/8, ::1); the guest’s own loopback, not the host. See the loopback-vs-host watch-out |
"link-local" | Link-local addresses (169.254.0.0/16, fe80::/10) excluding metadata |
"metadata" | Cloud metadata endpoints (169.254.169.254) |
"multicast" | Multicast addresses (224.0.0.0/4, ff00::/8) |
"host" | The host machine, reached via host.microsandbox.internal. The right group for “let the sandbox reach my host’s localhost”, not "loopback" |
. becomes a suffix match: .example.com matches api.example.com but not example.com.
