docs/sdk/python/proxies.mdx
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.
<Note>Outbound proxies are local-only. Cloud sandbox creation rejects this setting.</Note>
from microsandbox import OutboundProxy, Sandbox
sandbox = await Sandbox.create(
"worker",
image="python",
proxy=OutboundProxy.socks5("127.0.0.1:1080"),
)
| Parameter | Type | Default | Description |
|---|---|---|---|
| proxy | OutboundProxy | None | None | Single proxy used for outbound sandbox connections |
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(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(variable: str) -> SecretSource
Create a host environment-variable reference for a SOCKS5 password. Import SecretSource from microsandbox.