docs/sdk/go/networking.mdx
Configure sandbox networking. See Networking for usage and policy concepts.
func WithNetwork(net *NetworkConfig) SandboxOption
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.
func WithPorts(ports map[uint16]uint16) SandboxOption
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.
func WithPortsUDP(ports map[uint16]uint16) SandboxOption
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.
func WithPortBindings(bindings ...PortBinding) SandboxOption
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.
Factory namespace returning high-level *NetworkConfig values. Access through the package-level NetworkPolicy value.
func (networkPolicyFactory) FromProfiles(profiles ...NetworkProfile) *NetworkConfig
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.
func (networkPolicyFactory) FromProfilesChecked(profiles ...NetworkProfile) (*NetworkConfig, error)
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.
func (networkPolicyFactory) None() *NetworkConfig
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.
func (networkPolicyFactory) AllowAll() *NetworkConfig
m.WithNetwork(m.NetworkPolicy.AllowAll())
Permit all network traffic, including private addresses and the host machine.
<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">Config with allow defaults in both directions.</div> </div> </div>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()
Allow gateway DNS over UDP and TCP port 53
<p className="msb-label">Returns</p>Rule.DenyDNS()
Deny gateway DNS over UDP and TCP port 53
<p className="msb-label">Returns</p>network := m.NetworkPolicy.FromProfiles(m.NetworkProfilePublic)
network.Rules = append([]m.PolicyRule{m.Rule.DenyDNS()}, network.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"},
},
},
}),
)
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" |
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 | Local rate limits grouped by direction. nil means unlimited. Cloud network configuration does not expose this field |
| 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 |
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 |
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 |
type TLSConfig struct {
Bypass []string
VerifyUpstream *bool
InterceptedPorts []uint16
BlockQUIC *bool
CACert string
CAKey string
UpstreamCACerts []string
ScopedUpstreamCACerts []ScopedUpstreamCACert
ScopedVerifyUpstream []ScopedVerifyUpstream
}
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 |
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 |
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 |
type NetworkRateLimiterConfig struct {
Egress *RateLimiterConfig
Ingress *RateLimiterConfig
}
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},
},
},
}),
)
Local network rate limits grouped by direction. An omitted direction is unlimited. Cloud network configuration does not expose rate limits.
| Field | Type | Description |
|---|---|---|
| Egress | *RateLimiterConfig | Guest-to-runtime rate limiter |
| Ingress | *RateLimiterConfig | Runtime-to-guest rate limiter |
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 |
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 |
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 |
type PortProtocol string
Identifies the protocol for an exposed sandbox service.
| Constant | Value | Description |
|---|---|---|
PortProtocolTCP | "tcp" | TCP port mapping |
PortProtocolUDP | "udp" | UDP port mapping |
type PolicyAction string
The action half of a PolicyRule.
| Constant | Value | Description |
|---|---|---|
PolicyActionAllow | "allow" | Permit the traffic |
PolicyActionDeny | "deny" | Drop the traffic silently |
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 |
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) |
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 |