---
title: Proxies
"og:title": Rust SDK Proxies reference
description: Route outbound sandbox connections through an HTTP CONNECT, SOCKS4, or SOCKS5 proxy with the Rust SDK.
---

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

See [Proxies](/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
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
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="http-connect">http_connect()</span>

```rust
fn http_connect(self, address: impl Into<String>) -> HttpConnectProxyBuilder
```

Select an HTTP CONNECT proxy at `IP:port`. It supports TCP only. Use the returned builder to enable optional HTTP Basic authentication.

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

```rust
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
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
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
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.

## HttpConnectProxyBuilder

Protocol-specific builder returned by [`OutboundProxyBuilder::http_connect()`](#http-connect). It carries the proxy address and is finalized when returned from the `.proxy()` callback.

### credentials()

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

Set optional HTTP CONNECT username/password authentication. Pass `SecretSource::env("HTTP_CONNECT_PASSWORD")` as `password`; store-backed sources are not supported for proxy credentials. HTTP Basic permits an empty username for token-only authentication; a non-empty username must not contain `:` or control characters. The resolved password must not be empty.

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
fn env(var: impl Into<String>) -> SecretSource
```

Create a host environment-variable reference for a SOCKS5 or HTTP CONNECT password. Import `SecretSource` from `microsandbox`.

## OutboundProxy

Declarative outbound proxy configuration stored in the sandbox's durable network specification. `Socks5Credentials` and [`HttpConnectCredentials`](#httpconnectcredentials) contain a password source, not the resolved password.

| Variant | Fields | Description |
|---------|--------|-------------|
| `HttpConnect` | `address: SocketAddr`, `credentials: Option<HttpConnectCredentials>` | HTTP proxy address and optional username/password credentials |
| `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 |

## HttpConnectCredentials

Environment-backed username and password reference stored on [`OutboundProxy::HttpConnect`](#outboundproxy). It holds the username and a host environment variable name, never the resolved password. Create it through [`HttpConnectProxyBuilder::credentials()`](#httpconnectproxybuilder).