YUME Internet freedom by FixCraft
On this page

YUME quick start

This starts the native Linux client and daemon with schema-1 configuration, TLS/H2, hybrid authentication, and a local SOCKS5 listener. YUME explained shows how the pieces fit together.

Build

git clone https://github.com/FixCraft-Inc/yume.git
cd yume
./ezbuild.sh --tests

The normal build produces build/bin/yume, build/bin/yumed, build/bin/yume-setup and build/bin/yume-doctor. It prepares the pinned, patched OpenSSL required by the native TLS profile and uses a bounded build job count. It does not prepare or change the separate BaseFWX checkout. Native Linux applications also need libsystemd development files; see build requirements.

Use an isolated build directory for a sanitizer or shared SDK build.

Create a local kit

yume-setup makes the kit and yume-doctor checks it. Both are built beside yume and make their keys with the same OpenSSL release:

build/bin/yume-setup init \
  --host localhost --port 8443 \
  --output "$PWD/yume-kit" --client-name laptop
build/bin/yume-doctor --config yume-kit/server/yumed.json
build/bin/yume-doctor --config yume-kit/client/yume.json

The output directory must not exist. Setup atomically publishes owner-only credentials, a separate access PSK for the client identity, TLS material, server and client configurations, and a static cover site. Admission, access, TLS and composite identity credentials have distinct purposes. Do not replace them with one shared key or expose them in logs or source control.

To move the client directory to another device, seal it into one file and import it there with the code the seal prints:

build/bin/yume --seal-kit yume-kit/client --output laptop.kit
# on the other device, type the code when asked
yume --import-kit laptop.kit --into ~/.config/yume/kits/laptop

The destination must be a new directory. Use the GUI-managed $XDG_CONFIG_HOME/yume/kits/<name> location if the imported kit should appear in yume-gui.

Send the code by another channel than the file. The sealed file has no readable header and holds the client’s private key, access PSK and admission key, so treat it like the directory.

The local kit uses a development CA and sample cover content. For a public endpoint, choose the cover content and a certificate trusted by its visitors. Use a DNS name for endpoint.host. A fixed dial address belongs in the client’s endpoint.connect_address; hostname and admission checks still use host.

Start both processes

Validate the daemon configuration, then run it in one terminal:

build/bin/yumed --config yume-kit/server/yumed.json --validate
build/bin/yumed --config yume-kit/server/yumed.json

In another terminal:

build/bin/yume --config yume-kit/client/yume.json --validate
build/bin/yume --config yume-kit/client/yume.json

The daemon serves ordinary HTTPS cover and authenticated tunnel traffic on its configured listener. The generated kit needs no separate Node process. Port 8443 needs no privileged bind capability. A managed service on port 443 can grant only CAP_NET_BIND_SERVICE; see packaging.

The client exposes SOCKS5 on 127.0.0.1:1080. For example:

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

CONNECT resolves destination names on the daemon. Every resolved address must satisfy the service’s destination policy. The kit permits public destinations; private or loopback destinations need an explicit network in the corresponding server adapter. UDP ASSOCIATE uses the configured packet service and preserves individual datagrams. Local SOCKS connections are refused while no YTP session is active. The client reconnects with bounded backoff after session loss. Stop either process with SIGINT or SIGTERM.

Validate and extend

ctest --test-dir build --output-on-failure
build/bin/yume --version
build/bin/yumed --version

For other hosts, provision a kit for the endpoint’s DNS name and move each client bundle through an authenticated channel. Keep the offline CA private material off the server. Run doctor and --validate as the identity that will run the program. Security policy has no command-line overrides. The client’s run settings, listed in yume --help, change only the address it dials and its SOCKS5 listener.

The native development guide owns detailed credential, managed Linux TUN, packet policy, reconnect and embedding guidance. ABI.md describes the experimental SDK, which the Android client uses. yume --seal-kit turns a client directory into the one file and code that client imports. This quick start connects directly to an explicitly configured server. TCP circuits through two or three servers of one operator’s cluster are also implemented, with their own setup and consent rules in cluster 1. Decentralized discovery remains planned.