Proxies

Configure one HTTP CONNECT, SOCKS4, or SOCKS5 proxy for outbound sandbox traffic. The guest connects to its normal destination; microsandbox routes eligible traffic through the proxy on the host. Set sandbox_defaults.outbound_proxy in global configuration for a shared default. Administrators can enforce or clear it through managed configuration, which takes precedence over per-sandbox CLI and SDK options.

Supported proxies

Proxy	Authentication	Traffic	Availability
HTTP CONNECT	None	TCP	SDKs and CLI
SOCKS4	None	TCP	SDKs and CLI
SOCKS4	Optional user ID	TCP	SDKs and CLI
SOCKS5	None	TCP and non-DNS UDP	SDKs and CLI
SOCKS5	Optional username and password	TCP and non-DNS UDP	SDKs and CLI

You can configure only one proxy for a sandbox. A SOCKS4 user ID identifies the caller; it is not a password.

Configure a proxy

import { Sandbox } from "microsandbox";

await using sb = await Sandbox.builder("proxied")
  .image("python")
  .proxy((p) => p.socks5("127.0.0.1:1080"))
  .create();

use microsandbox::Sandbox;

let sb = Sandbox::builder("proxied")
    .image("python")
    .proxy(|p| p.socks5("127.0.0.1:1080"))
    .create()
    .await?;

from microsandbox import OutboundProxy, Sandbox

sb = await Sandbox.create(
    "proxied",
    image="python",
    proxy=OutboundProxy.socks5("127.0.0.1:1080"),
)

sb, err := m.CreateSandbox(ctx, "proxied",
    m.WithImage("python"),
    m.WithProxy(m.SOCKS5Proxy("127.0.0.1:1080")),
)

sb = Microsandbox::Sandbox.create(
  "proxied",
  image: "python",
  proxy: Microsandbox::OutboundProxy.socks5("127.0.0.1:1080")
)

# Choose one:
msb create python --name proxied --proxy http://127.0.0.1:3128
msb create python --name proxied --proxy socks4://127.0.0.1:1080
msb create python --name proxied --proxy socks5://127.0.0.1:1080

SDK addresses use IP:port. The msb run and msb create commands accept --proxy http://IP:port, socks4://IP:port, or socks5://IP:port. Proxy URIs reject user information, paths, query parameters, and fragments; SOCKS authentication uses separate CLI flags.

HTTP CONNECT

HTTP CONNECT opens a TCP tunnel through an HTTP proxy. It does not support proxy authentication or UDP. microsandbox resolves and checks the destination using its normal DNS and egress policy before sending the destination IP and port in the CONNECT request. The proxy address itself must be an IP address with a port. The selected msb runtime must support HTTP CONNECT. When using an older runtime, the SDK requests an upgrade before creating or replacing a sandbox.

.proxy((p) => p.httpConnect("127.0.0.1:3128"))

.proxy(|p| p.http_connect("127.0.0.1:3128"))

proxy=OutboundProxy.http_connect("127.0.0.1:3128")

m.WithProxy(m.HTTPConnectProxy("127.0.0.1:3128"))

msb run alpine --proxy http://127.0.0.1:3128

SOCKS4 user ID

Add an optional user ID through an SDK or --socks4-user-id in the CLI.

.proxy((p) => p.socks4("127.0.0.1:1080").userId("sandbox"))

.proxy(|p| p.socks4("127.0.0.1:1080").user_id("sandbox"))

proxy=OutboundProxy.socks4("127.0.0.1:1080", user_id="sandbox")

m.WithProxy(m.SOCKS4Proxy(
    "127.0.0.1:1080",
    m.SOCKS4ProxyOptions{UserID: "sandbox"},
))

proxy = Microsandbox::OutboundProxy.socks4("127.0.0.1:1080").user_id("sandbox")

msb run alpine \
  --proxy socks4://127.0.0.1:1080 \
  --socks4-user-id sandbox

The user ID must contain 1–255 bytes and cannot contain a null byte. Omit it to use SOCKS4 without a user ID.

SOCKS5 credentials

SOCKS5 supports optional username/password authentication. Passwords are loaded from a host environment variable rather than placed directly in configuration.

.proxy((proxy) =>
  proxy.socks5("127.0.0.1:1080").credentials(
    "sandbox",
    SecretSource.env("SOCKS5_PASSWORD"),
  ),
)

.proxy(|proxy| {
    proxy.socks5("127.0.0.1:1080").credentials(
        "sandbox",
        SecretSource::env("SOCKS5_PASSWORD"),
    )
})

proxy = OutboundProxy.socks5("127.0.0.1:1080").credentials(
    "sandbox",
    SecretSource.env("SOCKS5_PASSWORD"),
)

proxy := m.SOCKS5Proxy("127.0.0.1:1080").Credentials(
    "sandbox",
    m.SecretSourceEnv("SOCKS5_PASSWORD"),
)
m.WithProxy(proxy)

proxy = Microsandbox::OutboundProxy.socks5("127.0.0.1:1080").credentials(
  "sandbox",
  Microsandbox::SecretSource.env("SOCKS5_PASSWORD")
)

msb run alpine \
  --proxy socks5://127.0.0.1:1080 \
  --socks5-username sandbox \
  --socks5-password-env SOCKS5_PASSWORD

Password source: Set the password in a host environment variable, the only supported source. Configuration stores only the variable name, such as SOCKS5_PASSWORD, never the password.
When changes apply: The password is read when the sandbox starts. Restart the sandbox after changing it.
Requirements: The username and password must each contain 1–255 bytes. Startup fails if the password variable is missing, empty, or invalid.

SOCKS5 authentication does not encrypt credentials in transit. Use a trusted local or private proxy, or encrypt the connection separately.

Behavior and limits

Network policy is evaluated against the sandbox’s actual destination before the proxy connection is opened.
HTTP CONNECT and SOCKS4 support TCP only. Non-DNS UDP is blocked while either is configured; SOCKS4 also cannot reach IPv6 destinations.
SOCKS5 uses CONNECT for TCP and UDP ASSOCIATE for non-DNS UDP.
DNS uses microsandbox’s DNS forwarder instead of the configured proxy. This includes plain DNS, DNS-over-TCP, and DNS-over-TLS.
Connections to host.microsandbox.internal bypass the proxy and continue to target the microsandbox host.
Each TCP connection opens its own proxy connection and handshake. Each UDP flow opens its own SOCKS5 control connection and UDP association.
TLS interception and secret injection continue to work as configured.

Reference

For exact proxy APIs, see TypeScript, Rust, Python, or Go. For CLI flags, see Sandbox commands.

Getting Started

Sandboxes

Networking

Deep dive

Troubleshooting

Supported proxies

Configure a proxy

HTTP CONNECT

SOCKS4 user ID

SOCKS5 credentials

Behavior and limits

Reference

​Supported proxies

​Configure a proxy

​HTTP CONNECT

​SOCKS4 user ID

​SOCKS5 credentials

​Behavior and limits

​Reference

​Related

Supported proxies

Configure a proxy

HTTP CONNECT

SOCKS4 user ID

SOCKS5 credentials

Behavior and limits

Reference

Related