> ## Documentation Index
> Fetch the complete documentation index at: https://microsanbox-staging-toks-cloud-snapshot-contracts.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Proxies

> Rust SDK - Proxy API reference

Configure one SOCKS4 or SOCKS5 proxy for outbound sandbox connections with [`SandboxBuilder::proxy()`](#proxy). Proxy protocols are mutually exclusive.

See [Proxy](/networking/outbound-proxy) for routing behavior, security considerations, and limits.

<Note>Outbound proxies are local-only. Cloud sandbox creation rejects this setting.</Note>

## Typical flow

```rust theme={null}
use microsandbox::Sandbox;

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

## SandboxBuilder

### <span id="proxy">proxy()</span>

```rust theme={null}
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`](#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()`](#proxy).

### <span id="socks4">socks4()</span>

```rust theme={null}
fn socks4(self, address: impl Into<String>) -> Socks4ProxyBuilder
```

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

### <span id="socks5">socks5()</span>

```rust theme={null}
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`](#socks5proxybuilder).

## Socks4ProxyBuilder

Protocol-specific builder returned by [`OutboundProxyBuilder::socks4()`](#socks4).

### user\_id()

```rust theme={null}
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()`](#socks5). It carries the proxy address and is finalized when returned from the `.proxy()` callback.

### credentials()

```rust theme={null}
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()

```rust theme={null}
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 |