Networking

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 for the conceptual overview and TLS Interception for proxy details. The Go SDK exposes networking as a NetworkConfig struct passed to WithNetwork. Outbound proxies use the sibling WithProxy option. Common policy shapes come from the NetworkPolicy factory; custom firewalls are built by populating NetworkConfig.Rules directly.

Functions

m.WithNetwork()

func WithNetwork(net *NetworkConfig) SandboxOption

Example

sb, err := m.CreateSandbox(ctx, "worker",
    m.WithImage("alpine"),
    m.WithNetwork(m.NetworkPolicy.FromProfiles(m.NetworkProfilePublic)),
)

Set the network configuration for the sandbox. Pass a profile policy from the NetworkPolicy factory, or a custom NetworkConfig value with your own rules, DNS, TLS, and port settings.

Parameters

net*NetworkConfig

Network stack configuration.

Returns

SandboxOption

Option to pass to CreateSandbox.

m.WithPorts()

func WithPorts(ports map[uint16]uint16) SandboxOption

Example

sb, err := m.CreateSandbox(ctx, "api",
    m.WithImage("python:3.12"),
    m.WithPorts(map[uint16]uint16{8080: 8080}),
)

Make TCP services running in the sandbox reachable on localhost ports on the host. Each map entry exposes the guest port (value) on the host port (key), bound to 127.0.0.1. Called multiple times, the maps merge.

Parameters

portsmap[uint16]uint16

Host port to guest port (TCP).

Returns

SandboxOption

Option to pass to CreateSandbox.

m.WithPortsUDP()

func WithPortsUDP(ports map[uint16]uint16) SandboxOption

Example

sb, err := m.CreateSandbox(ctx, "dns",
    m.WithImage("alpine"),
    m.WithPortsUDP(map[uint16]uint16{5353: 53}),
)

Make UDP services running in the sandbox reachable on localhost ports on the host. Each map entry exposes the guest port (value) on the host port (key), bound to 127.0.0.1. Called multiple times, the maps merge.

Parameters

portsmap[uint16]uint16

Host port to guest port (UDP).

Returns

SandboxOption

Option to pass to CreateSandbox.

m.WithPortBindings()

func WithPortBindings(bindings ...PortBinding) SandboxOption

Example

sb, err := m.CreateSandbox(ctx, "api",
    m.WithImage("python:3.12"),
    m.WithPortBindings(
        m.PortBinding{Bind: "0.0.0.0", HostPort: 8001, GuestPort: 8001},
        m.PortBinding{Bind: "127.0.0.1", HostPort: 5353, GuestPort: 53, Protocol: m.PortProtocolUDP},
    ),
)

Make services running in the sandbox reachable on explicit host addresses and ports. Use this when the default 127.0.0.1 bind is too restrictive, for example to expose a port on 0.0.0.0. Accepts one or more PortBinding values.

Parameters

bindings…PortBinding

Explicit bind address, host port, guest port, and protocol.

Returns

SandboxOption

Option to pass to CreateSandbox.

NetworkPolicy

Factory namespace returning high-level *NetworkConfig values. Access through the package-level NetworkPolicy value.

NetworkPolicy.FromProfiles()

func (networkPolicyFactory) FromProfiles(profiles ...NetworkProfile) *NetworkConfig

Example

m.WithNetwork(m.NetworkPolicy.FromProfiles(
    m.NetworkProfilePublic,
    m.NetworkProfilePrivate,
))

Build a deny-by-default policy from NetworkProfilePublic, NetworkProfilePrivate, and NetworkProfileHost. Duplicate profiles are ignored, rules use canonical order, and each non-empty set receives one gateway DNS rule. An empty profile set permits no egress and adds no DNS; ingress defaults to allow. FromProfiles panics if passed a value other than the three package-defined NetworkProfile constants.

Returns

*NetworkConfig

Config containing canonical profile and DNS rules.

NetworkPolicy.FromProfilesChecked()

func (networkPolicyFactory) FromProfilesChecked(profiles ...NetworkProfile) (*NetworkConfig, error)

Example

network, err := m.NetworkPolicy.FromProfilesChecked(profiles...)
if err != nil {
    return err
}

Builds the same canonical deny-by-default policy as FromProfiles, but returns an error instead of panicking when a profile is unknown. Use this method for values derived from runtime input.

Returns

*NetworkConfig

Config containing canonical profile and DNS rules.

error

Non-nil when any requested profile is unknown.

NetworkPolicy.None()

func (networkPolicyFactory) None() *NetworkConfig

Example

m.WithNetwork(m.NetworkPolicy.None())

Block all network traffic in both directions. The network interface remains present; Exec and FS still work because they use the host-guest channel.

Returns

*NetworkConfig

Config with deny defaults in both directions.

NetworkPolicy.AllowAll()

func (networkPolicyFactory) AllowAll() *NetworkConfig

Example

m.WithNetwork(m.NetworkPolicy.AllowAll())

Permit all network traffic, including private addresses and the host machine.

Returns

*NetworkConfig

Config with allow defaults in both directions.

Rule

The package-level Rule factory provides semantic low-level rules. Rule.AllowDNS() returns a PolicyRule allowing gateway UDP/53 and TCP/53; Rule.DenyDNS() returns its deny counterpart. Put Rule.DenyDNS() before profile-generated rules when you need to override automatic DNS access.

Rule.AllowDNS()

Rule.AllowDNS()

Allow gateway DNS over UDP and TCP port 53

Returns

PolicyRule

Rule.DenyDNS()

Rule.DenyDNS()

Deny gateway DNS over UDP and TCP port 53

Returns

PolicyRule

network := m.NetworkPolicy.FromProfiles(m.NetworkProfilePublic)
network.Rules = append([]m.PolicyRule{m.Rule.DenyDNS()}, network.Rules...)

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. A broad rule placed before a narrow one swallows it, so put specific rules first.

Example

sb, err := m.CreateSandbox(ctx, "ci-runner",
    m.WithImage("python:3.12"),
    m.WithNetwork(&m.NetworkConfig{
        DefaultEgress:  m.PolicyActionDeny,
        DefaultIngress: m.PolicyActionAllow,
        Rules: []m.PolicyRule{
            {Action: m.PolicyActionDeny, Destination: "10.0.0.5"},      // specific first
            {Action: m.PolicyActionAllow, Destination: "10.0.0.0/8"},   // broad fallthrough
            {
                Action:      m.PolicyActionAllow,
                Direction:   m.PolicyDirectionEgress,
                Destination: ".internal",
                Protocols:   []m.PolicyProtocol{m.PolicyProtocolTCP},
                Ports:       []string{"8000-9000"},
            },
        },
    }),
)

Constants

Destination groups

Used by PolicyRule.Destination

The Destination field on PolicyRule accepts these well-known group names alongside literal CIDRs and domains. A domain prefixed with . becomes a suffix match: .example.com matches api.example.com but not example.com.

Value	Description
`"public"`	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 Reaching the host
`"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"`

Types

NetworkConfig

Used by WithNetwork() · returned by NetworkPolicy

type NetworkConfig struct {
    Rules                    []PolicyRule
    DefaultEgress           PolicyAction
    DefaultIngress          PolicyAction
    DenyDomains             []string
    DenyDomainSuffixes      []string
    DNS                      *DNSConfig
    DNSRebindProtection     *bool
    TLS                      *TLSConfig
    Ports                    map[uint16]uint16
    PortBindings             []PortBinding
    IPv4Pool                 string
    IPv6Pool                 string
    MaxConnections           *uint
    RateLimiter              *NetworkRateLimiterConfig
    OnSecretViolation        ViolationAction
    TrustHostCAs             *bool
}

The full network stack configuration passed via WithNetwork.

Field	Type	Description
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 domain names to refuse DNS resolution for
DenyDomainSuffixes	`[]string`	Domain suffixes (e.g. `.ads`) to block, including the apex and any subdomain
DNS	`*DNSConfig`	In-VM DNS proxy settings
DNSRebindProtection	`*bool`	Legacy convenience for `DNS.RebindProtection`. When `DNS` is also set, the nested value wins
TLS	`*TLSConfig`	Transparent TLS interception proxy settings
Ports	`map[uint16]uint16`	Host to guest TCP port mappings bound to `127.0.0.1`
PortBindings	`[]PortBinding`	Host to guest mappings with explicit bind addresses
IPv4Pool	`string`	Pool used to derive per-sandbox `/30` guest subnets. Defaults to `172.16.0.0/12`
IPv6Pool	`string`	Pool used to derive per-sandbox `/64` guest prefixes. Defaults to `fd42:6d73:62::/48`
MaxConnections	`*uint`	Cap on concurrent network connections from the sandbox
RateLimiter	`*NetworkRateLimiterConfig`	Rate limits grouped by direction. `nil` means unlimited
OnSecretViolation	`ViolationAction`	Sandbox-wide action when a secret is sent to a disallowed host. Per-secret overrides via `SecretEntry.OnViolation`
TrustHostCAs	`*bool`	Ship the host’s extra CA bundles into the guest. Opt-in for corporate MITM proxies whose gateway CA is unknown to the guest’s stock bundle

PolicyRule

Used by NetworkConfig.Rules

type PolicyRule struct {
    Action      PolicyAction
    Direction   PolicyDirection
    Destination string
    Protocol    PolicyProtocol
    Protocols   []PolicyProtocol
    Port        string
    Ports       []string
}

A single firewall rule. Ingress rules carrying ICMP protocols are rejected at sandbox creation, since the host has no inbound ICMP path; use PolicyDirectionEgress for ICMP.

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 `"*"`
Protocol	`PolicyProtocol`	Legacy single-protocol field. The empty string means any. Prefer `Protocols` when matching multiple
Protocols	`[]PolicyProtocol`	Protocol set. Empty means any
Port	`string`	Single port (`"443"`) or range (`"8000-9000"`)
Ports	`[]string`	Several port values at once

DNSConfig

Used by NetworkConfig.DNS

type DNSConfig struct {
    RebindProtection *bool
    Nameservers      []string
    QueryTimeoutMs   *uint64
}

In-VM DNS proxy configuration.

Field	Type	Description
RebindProtection	`*bool`	Block DNS responses resolving to private IPs. Defaults to `true` when unset
Nameservers	`[]string`	Upstream resolvers (e.g. `"1.1.1.1:53"`). Replaces `/etc/resolv.conf` when non-empty
QueryTimeoutMs	`*uint64`	Per-DNS-query timeout in milliseconds

TLSConfig

Used by NetworkConfig.TLS

type TLSConfig struct {
    Bypass                    []string
    VerifyUpstream            *bool
    InterceptedPorts          []uint16
    BlockQUIC                 *bool
    CACert                    string
    CAKey                     string
    UpstreamCACerts           []string
    ScopedUpstreamCACerts     []ScopedUpstreamCACert
    ScopedVerifyUpstream      []ScopedVerifyUpstream
}

Example

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},
        },
    }),
)

Transparent HTTPS inspection proxy configuration.

Field	Type	Description
Bypass	`[]string`	Domain patterns (supports `*.suffix`) to skip MITM. Use for domains with certificate pinning
VerifyUpstream	`*bool`	Verify upstream server certificates. Defaults to `true`. Set `false` only for self-signed servers
InterceptedPorts	`[]uint16`	TCP ports where TLS is intercepted. Defaults to `[443]`
BlockQUIC	`*bool`	Block QUIC on intercepted ports to force 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 every upstream host
ScopedUpstreamCACerts	`[]ScopedUpstreamCACert`	Host-pattern-scoped CA bundles trusted only for matching upstream hosts
ScopedVerifyUpstream	`[]ScopedVerifyUpstream`	Host-pattern-scoped upstream certificate verification overrides

ScopedUpstreamCACert

Used by TLSConfig.ScopedUpstreamCACerts

type ScopedUpstreamCACert struct {
    Pattern string
    Path    string
}

Host-scoped upstream CA bundle configuration.

Field	Type	Description
Pattern	`string`	Exact host or `*.suffix` wildcard
Path	`string`	CA bundle path trusted for matching upstream hosts

ScopedVerifyUpstream

Used by TLSConfig.ScopedVerifyUpstream

type ScopedVerifyUpstream struct {
    Pattern string
    Verify  bool
}

Host-scoped upstream certificate verification override.

Field	Type	Description
Pattern	`string`	Exact host or `*.suffix` wildcard
Verify	`bool`	Whether to verify certificates for matching upstream hosts

NetworkRateLimiterConfig

Used by NetworkConfig.RateLimiter

type NetworkRateLimiterConfig struct {
    Egress  *RateLimiterConfig
    Ingress *RateLimiterConfig
}

Example

sb, err := m.CreateSandbox(ctx, "throttled",
    m.WithImage("python"),
    m.WithNetwork(&m.NetworkConfig{
        RateLimiter: &m.NetworkRateLimiterConfig{
            Egress: &m.RateLimiterConfig{
                Bandwidth: &m.TokenBucketConfig{Size: 1 << 20, RefillTime: time.Second, OneTimeBurst: 512 << 10},
                Ops:       &m.TokenBucketConfig{Size: 1000, RefillTime: time.Second},
            },
        },
    }),
)

Network rate limits grouped by direction. An omitted direction is unlimited.

Field	Type	Description
Egress	`*RateLimiterConfig`	Guest-to-runtime rate limiter
Ingress	`*RateLimiterConfig`	Runtime-to-guest rate limiter

RateLimiterConfig

Held by NetworkRateLimiterConfig

type RateLimiterConfig struct {
    Bandwidth *TokenBucketConfig
    Ops       *TokenBucketConfig
}

Rate limiter for one traffic direction. Caps bandwidth (bytes) and packet rate (frames) independently; a nil bucket leaves that dimension unlimited.

Field	Type	Description
Bandwidth	`*TokenBucketConfig`	Byte budget; one token per byte of frame data
Ops	`*TokenBucketConfig`	Packet budget; one token per network frame

TokenBucketConfig

Used by RateLimiterConfig

type TokenBucketConfig struct {
    Size         uint64
    RefillTime   time.Duration
    OneTimeBurst uint64
}

One token bucket of a rate limiter. The bucket starts full and refills continuously: Size tokens every RefillTime. The one-time burst is spent before the regular budget and never refills.

Field	Type	Description
Size	`uint64`	Bucket capacity in tokens: bytes for bandwidth buckets, frames for ops buckets. Must be greater than zero
RefillTime	`time.Duration`	Time to refill `Size` tokens. Must be at least one millisecond
OneTimeBurst	`uint64`	Extra startup-only tokens. Optional

PortBinding

Used by WithPortBindings() · NetworkConfig.PortBindings

type PortBinding struct {
    Bind      string
    HostPort  uint16
    GuestPort uint16
    Protocol  PortProtocol
}

A host-to-guest port mapping with an explicit host bind address. Protocol defaults to TCP when empty. Use Bind: "0.0.0.0" to expose the published port on all IPv4 interfaces.

Field	Type	Description
Bind	`string`	Host IP address to bind, such as `127.0.0.1`, `0.0.0.0`, or `::`
HostPort	`uint16`	Port on the host
GuestPort	`uint16`	Port inside the sandbox
Protocol	`PortProtocol`	`PortProtocolTCP` or `PortProtocolUDP`. Empty defaults to TCP

PortProtocol

Used by PortBinding.Protocol

type PortProtocol string

Identifies the protocol for an exposed sandbox service.

Constant	Value	Description
`PortProtocolTCP`	`"tcp"`	TCP port mapping
`PortProtocolUDP`	`"udp"`	UDP port mapping

PolicyAction

Used by PolicyRule.Action · NetworkConfig.DefaultEgress

type PolicyAction string

The action half of a PolicyRule.

Constant	Value	Description
`PolicyActionAllow`	`"allow"`	Permit the traffic
`PolicyActionDeny`	`"deny"`	Drop the traffic silently

PolicyDirection

Used by PolicyRule.Direction

type PolicyDirection string

The direction half of a PolicyRule. The Go SDK follows the Python naming (egress/ingress); the wire format carries these values.

Constant	Value	Description
`PolicyDirectionEgress`	`"egress"`	Traffic leaving the sandbox
`PolicyDirectionIngress`	`"ingress"`	Traffic entering the sandbox
`PolicyDirectionAny`	`"any"`	Rule applies in either direction

PolicyProtocol

Used by PolicyRule.Protocol · PolicyRule.Protocols

type PolicyProtocol string

The protocol half of a PolicyRule.

Constant	Value	Description
`PolicyProtocolTCP`	`"tcp"`	TCP traffic
`PolicyProtocolUDP`	`"udp"`	UDP traffic
`PolicyProtocolICMPv4`	`"icmpv4"`	ICMPv4 traffic (egress only)
`PolicyProtocolICMPv6`	`"icmpv6"`	ICMPv6 traffic (egress only)

NetworkProfile

type NetworkProfile string

Composable profile names accepted by NetworkPolicy.FromProfiles().

Constant	Value	Description
`NetworkProfilePublic`	`"public"`	Public internet addresses
`NetworkProfilePrivate`	`"private"`	Private/LAN ranges
`NetworkProfileHost`	`"host"`	Sandbox host gateway addresses

Getting Started

SDKs

CLI

Functions

m.WithNetwork()

m.WithPorts()

m.WithPortsUDP()

m.WithPortBindings()

NetworkPolicy

NetworkPolicy.FromProfiles()

NetworkPolicy.FromProfilesChecked()

NetworkPolicy.None()

NetworkPolicy.AllowAll()

Rule

Rule.AllowDNS()

Rule.DenyDNS()

Constants

Types

NetworkConfig

PolicyRule

DNSConfig

TLSConfig

ScopedUpstreamCACert

ScopedVerifyUpstream

NetworkRateLimiterConfig

RateLimiterConfig

TokenBucketConfig

PortBinding

PortProtocol

PolicyAction

PolicyDirection

PolicyProtocol

NetworkProfile

​Functions

​m.WithNetwork()

​m.WithPorts()

​m.WithPortsUDP()

​m.WithPortBindings()

​NetworkPolicy

​NetworkPolicy.FromProfiles()

​NetworkPolicy.FromProfilesChecked()

​NetworkPolicy.None()

​NetworkPolicy.AllowAll()

​Rule

​Rule.AllowDNS()

​Rule.DenyDNS()

​Constants

​Types

​NetworkConfig

​PolicyRule

​DNSConfig

​TLSConfig

​ScopedUpstreamCACert

​ScopedVerifyUpstream

​NetworkRateLimiterConfig

​RateLimiterConfig

​TokenBucketConfig

​PortBinding

​PortProtocol

​PolicyAction

​PolicyDirection

​PolicyProtocol

​NetworkProfile

Functions

m.WithNetwork()

m.WithPorts()

m.WithPortsUDP()

m.WithPortBindings()

NetworkPolicy

NetworkPolicy.FromProfiles()

NetworkPolicy.FromProfilesChecked()

NetworkPolicy.None()

NetworkPolicy.AllowAll()

Rule

Rule.AllowDNS()

Rule.DenyDNS()

Constants

Types

NetworkConfig

PolicyRule

DNSConfig

TLSConfig

ScopedUpstreamCACert

ScopedVerifyUpstream

NetworkRateLimiterConfig

RateLimiterConfig

TokenBucketConfig

PortBinding

PortProtocol

PolicyAction

PolicyDirection

PolicyProtocol

NetworkProfile