> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ns.rocks/llms.txt
> Use this file to discover all available pages before exploring further.

# Tunnel Egress Through Your Own Proxy

> Route machine egress through a Shadowsocks proxy with template primitives.

Nullspace does not ship a first-class proxy product surface in private beta.
You can still build a template that starts a Shadowsocks client and points your
workload at the local SOCKS proxy.

## Local SOCKS proxy

```python theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
from nullspace import Machine, Template, wait_for_port

builder = (
    Template.from_ubuntu_image("22.04")
    .apt_install(["shadowsocks-libev", "curl", "ca-certificates"])
    .set_runtime_envs(
        Machine.enable_tunnel(
            "proxy.example.com",
            "change-me",
            port=8388,
            method="aes-256-gcm",
            mode="socks5",
        )
    )
    .set_start_cmd(
        "ss-local -s $SS_SERVER -p $SS_SERVER_PORT "
        "-k $SS_PASSWORD -m $SS_METHOD -b 127.0.0.1 -l 1080",
        readiness=wait_for_port(1080),
    )
)
```

Applications can then use `socks5h://127.0.0.1:1080`:

```python theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
machine = Machine.create(template="my-proxy-template")
try:
    result = machine.commands.run(
        "curl --socks5-hostname 127.0.0.1:1080 https://ifconfig.me",
        shell=True,
    )
    print(result.stdout.strip())
finally:
    machine.kill()
```

## Transparent proxy variant

Transparent egress requires root networking privileges inside the guest and is
best kept to dedicated templates. Use `ss-redir` and explicit `iptables` rules:

```python theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
builder = (
    Template.from_ubuntu_image("22.04")
    .apt_install(["shadowsocks-libev", "iptables", "ca-certificates"])
    .set_runtime_envs(Machine.enable_tunnel("proxy.example.com", "change-me"))
    .set_start_cmd(
        "ss-redir -s $SS_SERVER -p $SS_SERVER_PORT -k $SS_PASSWORD "
        "-m $SS_METHOD -b 127.0.0.1 -l 1081 & "
        "iptables -t nat -A OUTPUT -p tcp -m owner ! --uid-owner root "
        "-j REDIRECT --to-ports 1081 && tail -f /dev/null"
    )
)
```

Prefer the local SOCKS variant unless you control the full template and have a
clear reason to intercept all TCP egress.

Concept: [Create](../concepts/create). API reference:
[buildTemplate](../api-reference), [createMachine](../api-reference), and
[execCommand](../api-reference).