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 single NetworkConfig struct passed to WithNetwork. Common 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.

When profile names come from JSON, configuration, environment variables, or other runtime input, use the checked variant instead:

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

NetworkPolicy.FromProfilesChecked()

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

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.

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.

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

Types

NetworkConfig

Used by WithNetwork() · returned by NetworkPolicy

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

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

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

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

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

ScopedUpstreamCACert

Used by TLSConfig.ScopedUpstreamCACerts

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

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

PortBinding

Used by WithPortBindings() · NetworkConfig.PortBindings

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

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

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

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

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

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

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"`

Getting Started

SDKs

CLI

Functions

m.WithNetwork()

m.WithPorts()

m.WithPortsUDP()

m.WithPortBindings()

NetworkPolicy

NetworkPolicy.FromProfiles()

NetworkPolicy.FromProfilesChecked()

NetworkPolicy.None()

NetworkPolicy.AllowAll()

Rule

Custom rules

Types

NetworkConfig

PolicyRule

DNSConfig

TLSConfig

ScopedUpstreamCACert

ScopedVerifyUpstream

PortBinding

PortProtocol

PolicyAction

PolicyDirection

PolicyProtocol

NetworkProfile

Destination groups

​Functions

​m.WithNetwork()

​m.WithPorts()

​m.WithPortsUDP()

​m.WithPortBindings()

​NetworkPolicy

​NetworkPolicy.FromProfiles()

​NetworkPolicy.FromProfilesChecked()

​NetworkPolicy.None()

​NetworkPolicy.AllowAll()

​Rule

​Custom rules

​Types

​NetworkConfig

​PolicyRule

​DNSConfig

​TLSConfig

​ScopedUpstreamCACert

​ScopedVerifyUpstream

​PortBinding

​PortProtocol

​PolicyAction

​PolicyDirection

​PolicyProtocol

​NetworkProfile

​Destination groups

Functions

m.WithNetwork()

m.WithPorts()

m.WithPortsUDP()

m.WithPortBindings()

NetworkPolicy

NetworkPolicy.FromProfiles()

NetworkPolicy.FromProfilesChecked()

NetworkPolicy.None()

NetworkPolicy.AllowAll()

Rule

Custom rules

Types

NetworkConfig

PolicyRule

DNSConfig

TLSConfig

ScopedUpstreamCACert

ScopedVerifyUpstream

PortBinding

PortProtocol

PolicyAction

PolicyDirection

PolicyProtocol

NetworkProfile

Destination groups