Proxies

Configure one SOCKS4 or SOCKS5 proxy for outbound sandbox connections with the proxy= argument to Sandbox.create(). 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

from microsandbox import OutboundProxy, Sandbox

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

Sandbox.create()

Parameter	Type	Default	Description
proxy	`OutboundProxy` `\| None`	`None`	Single proxy used for outbound sandbox connections

OutboundProxy

Frozen proxy configuration passed through Sandbox.create(proxy=...).

Class method	Returns	Description
`socks4(address, *, user_id=None)`	`OutboundProxy`	Configure a SOCKS4 proxy at `IP:port` with an optional user ID
`socks5(address)`	`OutboundProxy`	Configure a SOCKS5 proxy at `IP:port`

The SOCKS4 user_id must contain 1–255 bytes and no null byte. It identifies the caller; it is not a password.

credentials()

credentials(username: str, password: SecretSource) -> OutboundProxy

Return a SOCKS5 proxy with username/password authentication. Pass SecretSource.env("SOCKS5_PASSWORD") as password. Calling this method on a SOCKS4 proxy raises ValueError. 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. The username and resolved password must each contain 1–255 bytes.

SecretSource

env()

SecretSource.env(variable: str) -> SecretSource

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

Getting Started

SDKs

CLI

Typical flow

Sandbox.create()

OutboundProxy

credentials()

SecretSource

env()

​Typical flow

​Sandbox.create()

​OutboundProxy

​credentials()

​SecretSource

​env()

Typical flow

Sandbox.create()

OutboundProxy

credentials()

SecretSource

env()