Proxies

Configure one SOCKS4 or SOCKS5 proxy for outbound sandbox connections with SandboxBuilder::proxy(). Proxy protocols are mutually exclusive. See Proxy for routing behavior, security considerations, and limits.

Outbound proxies are local-only. Cloud sandbox creation rejects this setting.

Typical flow

use microsandbox::Sandbox;

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

SandboxBuilder

proxy()

fn proxy<P>(self, configure: impl FnOnce(OutboundProxyBuilder) -> P) -> Self
where
    P: OutboundProxyConfig

Select and configure the single outbound proxy for the sandbox. The callback receives an OutboundProxyBuilder and must return one protocol-specific builder. Invalid proxy configuration is retained by the sandbox builder and returned from build() or create() as MicrosandboxError::NetworkBuilder(BuildError::InvalidOutboundProxy).

OutboundProxyBuilder

Protocol selector passed to SandboxBuilder::proxy().

socks4()

fn socks4(self, address: impl Into<String>) -> Socks4ProxyBuilder

Select a SOCKS4 proxy at IP:port. The returned builder can optionally set a user ID.

socks5()

fn socks5(self, address: impl Into<String>) -> Socks5ProxyBuilder

Select a SOCKS5 proxy at IP:port. The parent sandbox builder validates and materializes the returned Socks5ProxyBuilder.

Socks4ProxyBuilder

Protocol-specific builder returned by OutboundProxyBuilder::socks4().

user_id()

fn user_id(self, user_id: impl Into<String>) -> Self

Set the optional SOCKS4 user ID. It must contain 1–255 bytes and no null byte. A user ID identifies the caller; it is not a password.

Socks5ProxyBuilder

Protocol-specific builder returned by OutboundProxyBuilder::socks5(). It carries the proxy address and is finalized when returned from the .proxy() callback.

credentials()

fn credentials(self, username: impl Into<String>, password: SecretSource) -> Self

Set optional SOCKS5 username/password authentication. Pass SecretSource::env("SOCKS5_PASSWORD") as password; store-backed sources are not supported for proxy credentials. The username and resolved password must each contain 1–255 bytes. The host environment variable is read once each time the sandbox starts. Changing it affects the next start, not a sandbox that is already running. config_json() and the database contain the source reference but never the resolved password.

SecretSource

env()

fn env(var: impl Into<String>) -> SecretSource

Create a host environment-variable reference for a SOCKS5 password. Import SecretSource from microsandbox.

OutboundProxy

Declarative outbound proxy configuration stored in the sandbox’s durable network specification. Socks5Credentials contains a password source, not the resolved password.

Variant	Fields	Description
`Socks4`	`address: SocketAddr`, `user_id: Option<String>`	SOCKS4 proxy address and optional user ID
`Socks5`	`address: SocketAddr`, `credentials: Option<Socks5Credentials>`	SOCKS5 proxy address and optional username/password credentials

Getting Started

SDKs

CLI

Typical flow

SandboxBuilder

proxy()

OutboundProxyBuilder

socks4()

socks5()

Socks4ProxyBuilder

user_id()

Socks5ProxyBuilder

credentials()

SecretSource

env()

OutboundProxy

​Typical flow

​SandboxBuilder

​proxy()

​OutboundProxyBuilder

​socks4()

​socks5()

​Socks4ProxyBuilder

​user_id()

​Socks5ProxyBuilder

​credentials()

​SecretSource

​env()

​OutboundProxy

Typical flow

SandboxBuilder

proxy()

OutboundProxyBuilder

socks4()

socks5()

Socks4ProxyBuilder

user_id()

Socks5ProxyBuilder

credentials()

SecretSource

env()

OutboundProxy