> Markdown version of https://tuna.am/en/docs/guides/proxy/. Documentation index: [llms.txt](https://tuna.am/en/llms.txt), full text in one file: [llms-full.txt](https://tuna.am/en/llms-full.txt). Any page is available as Markdown: append `.md` to its URL without the trailing slash.

# Connecting through a SOCKS5 proxy

Some corporate networks and isolated environments have no direct internet access: outbound traffic is allowed only through a SOCKS5 proxy. To make the tuna CLI work on such a network, give it the proxy address: the CLI will reach the API and connect tunnels to nodes through it. SOCKS5 is supported, including username and password authentication, in tuna-cli 0.42.0 and later.

## Setting the proxy

The proxy address has the format `socks5://[username:password@]host[:port]`. The default port is `1080`.

With the `--proxy` flag, available on every command:

```shell
tuna http 8080 --proxy socks5://proxy.corp.local:1080

```

With the `TUNA_PROXY` environment variable:

```shell
export TUNA_PROXY=socks5://user:password@proxy.corp.local:1080
tuna http 8080

```

With the `proxy` key in the [configuration file](https://tuna.am/en/docs/guides/config-file.md), so it applies to every run. There is no separate command for this key, so add it to the file by hand:

```yaml
---
version: "1"
apiKey: tak_***
proxy: socks5://user:password@proxy.corp.local:1080

```

If the proxy is set in more than one place, the flag takes precedence over the variable, and the variable over the config file.

The `socks5://` and `socks5h://` schemes behave the same: host names are always resolved by the proxy, so the CLI works even without DNS. Any other scheme, such as `http://`, fails with `only socks5:// is supported`, and the command does not start.

> **System proxy variables.** The CLI does not read `ALL_PROXY`, `HTTPS_PROXY`, or `NO_PROXY` — only `TUNA_PROXY`. Otherwise, for users with a system-wide proxy set up for the browser, tuna traffic would silently take a different route.

## What goes through the proxy

* All API requests and SSH session recording uploads.
* Tunnel connections to nodes: `http`, `tcp`, `ssh`, `app`, `postgres`, `mysql`, `redis`, `kubernetes`, and others, including [`tuna start`](https://tuna.am/en/docs/tunnels/guides/multi-tunnels.md).
* `tuna diagnose` checks.

Connections to your local service go directly: the proxy is only used to reach the internet.

## Background service

Pass the proxy in the tunnel command or set `TUNA_PROXY` before installing the [service](https://tuna.am/en/docs/tunnels/guides/service.md):

```shell
tuna service install -- tuna http 8080 --subdomain=web --proxy socks5://user:password@proxy.corp.local:1080

```

`install` removes `--proxy` from the service command line and passes the address to the service environment as `TUNA_PROXY`, so the proxy password does not show up in the process list.

## Diagnostics

The first line of `tuna diagnose` output shows which proxy the checks go through. The password is hidden:

```text
Proxy: socks5://user:xxxxx@proxy.corp.local:1080

```

Errors on connections through the proxy contain `via proxy` and the proxy address. For example, with a wrong password (in `tuna diagnose`, it appears in the `tuna API: FAIL` line):

```text
via proxy socks5://user:xxxxx@proxy.corp.local:1080: socks connect tcp proxy.corp.local:1080->api.tuna.am:443: username/password authentication failed

```

If the checks to nodes fail, make sure the proxy allows connections to port `443` on the addresses listed in [Using tuna in a corporate network](https://tuna.am/en/docs/guides/corporate-network.md#firewall-addresses).

## Limitations

* SOCKS5 only. HTTP proxies and the `NO_PROXY` exclusion list are not supported.
* [`tuna bastion ssh`](https://tuna.am/en/docs/bastion.md) runs the system `ssh` and does not use the proxy from the tuna settings. Configure `ProxyCommand` in `~/.ssh/config` for it.
* [Tuna Mesh](https://tuna.am/en/docs/mesh.md) uses WireGuard over UDP and cannot connect through a SOCKS5 proxy.
* Tuna Desktop and the [Kubernetes operator](https://tuna.am/en/docs/tunnels/guides/kubernetes-operator.md) do not support a proxy yet.
