Quick start

Overview

Start with one server, one client and the same Umbra version at both endpoints. You need a server address reachable by the client and a real fallback destination reachable by the server. The examples below contain placeholders, not usable credentials. Replace cover.example with a suitable actual TLS 1.3 destination and replace every identity placeholder using your own keygen output.

Details

Run umbra keygen in a private terminal. Keep x25519_private and mldsa_seed on the server; distribute x25519_public, mldsa_verify and a selected short_id securely to the client. Create server.toml, then start the server. Its startup probe must reach the configured destination. The client's server_name must belong to the server_names list and short_id must match an accepted short_ids entry.

Generate an identity

umbra keygen

umbra keygen does not generate short_id. Choose an even-length hexadecimal string of 0–16 characters (0–8 bytes) and use the same value on both endpoints. Replace the documentation address 198.51.100.10 with your reachable server address; keep the port consistent with the server listener.

Server template

listen = "0.0.0.0:443"
private_key = "<X25519_PRIVATE_BASE64>"
short_ids = ["<SHORT_ID_HEX>"]
dest = "cover.example:443"
server_names = ["cover.example"]
max_time_diff = "120s"
mldsa_seed = "<MLDSA_SEED_BASE64>"

Start the server

umbra server -c server.toml

Client template

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"

Start the client

umbra client -c client.toml

Check the connection

curl --socks5-hostname 127.0.0.1:1080 https://example.com/

Verify

Create client.toml and start the client. Configure an application to use SOCKS5 at 127.0.0.1:1080; SOCKS negotiation has no username/password authentication, so keep that listener local. A curl request through --socks5-hostname checks the complete path and delegates target hostname resolution through SOCKS. Stop both foreground processes with Ctrl-C. Once TCP works, the examples page shows how to add QUIC UDP to the same instance.