Connect applications and Clash-style clients

Connect existing applications and rule-based clients through local SOCKS5, with separate transport choices for TCP and UDP.

Overview

The Umbra client provides a local SOCKS5 endpoint. Applications or existing proxy clients pass requests to it, and Umbra connects to the remote Umbra server. Your familiar client can continue to handle rule-based routing, the interface and system proxy settings; Umbra itself is not a TUN interface, and installing the binary does not automatically proxy other applications.

1. Configure and start Umbra

First prepare the server using the server guide. Enter the matching identity material in client.toml; the placeholders below must be replaced and are not real credentials:

server = "198.51.100.10:443"
transport = "tcp"
public_key = "<X25519_PUBLIC_BASE64>"
short_id = "<SHORT_ID_HEX>"
server_name = "cover.example"
fingerprint = "chrome-latest"
mldsa_verify = "<MLDSA_VERIFY_BASE64>"
socks_listen = "127.0.0.1:1080"

server is your Umbra server address; server_name is the real site's SNI, matching the server configuration, not an arbitrary camouflage domain. After checking these values, run:

umbra client -c client.toml

Keep the loopback binding. Local SOCKS5 does not provide password authentication and must not be exposed directly to the public internet or an untrusted LAN.

2. Connect applications that support SOCKS5 directly

Select SOCKS5 in the application's proxy settings, enter 127.0.0.1 as the address and 1080 as the port, and leave the username and password blank. The application must run on the same device as Umbra or in the same network namespace with access to this loopback endpoint.

To verify an HTTPS request, replace the address below with the site you want to test:

curl --proxy socks5h://127.0.0.1:1080 https://example.com/

socks5h makes curl pass the destination domain to the proxy instead of resolving it locally first. Other applications' DNS behavior depends on their own settings; configuring SOCKS5 alone does not mean all DNS queries on the device go through the proxy.

3. Keep your rules with a Clash-style client

Merge the following node into the proxies list in your existing client configuration and select it in the proxy group you use. Do not overwrite the entire configuration:

proxies:
  - name: Umbra Local
    type: socks5
    server: 127.0.0.1
    port: 1080
    udp: true

The existing client still applies the rules, while local Umbra handles the remote connection. Make sure the rules do not send the remote Umbra server address back to Umbra Local, which could create a proxy loop. Consult your client's documentation for its specific rule, DNS and TUN settings.

This uses a standard SOCKS5 node, not native Umbra protocol support. VLESS / VMess / Trojan nodes and subscriptions cannot become Umbra nodes just by changing a name; both ends need matching Umbra programs and identity material.

4. Optional: Vision for TCP, QUIC for UDP

Merge this into your existing client.toml:

transport = "tcp"
udp_transport = "quic"
mux = false

Enable both listen and udp_listen on the server, and allow the corresponding TCP and UDP ports through the firewall. udp: true allows a Clash-style client to send UDP requests; it does not change the transport for TCP requests. The UDP relay endpoint is negotiated through SOCKS and does not require a fixed listener on UDP port 1080.

If UDP is unreachable, use TCP first to verify ordinary application requests. There is no automatic QUIC-to-TCP failover here; see transport modes for the available choices.

Verification and troubleshooting

Test one application directly through SOCKS5 before adding a rule-based client, so rule problems are not mistaken for transport failures.
Cross-check the public key, verification key, short ID, SNI and server address at both ends, and check the system clocks and firewall.
Verify TCP and UDP separately; successfully opening a web page does not mean UDP is working.
Adjust only one transport or performance option at a time; upgrade both ends together when updating adaptive mux.