YUME Internet freedom by FixCraft
Open source under AGPL-3.0

YUME For internet freedom.

Reach the internet through a server you control. YUME carries TCP, UDP and IP packets inside an encrypted connection shaped like Chrome visiting a website. Run the yume client and yumed server, or embed the same engine through its C library.

Yume (夢) means dream in Japanese. The dream behind it is internet freedom for everyone. Security comes first, then stealth, then usable speed.

Run a tunnel How it works Stealth model View source
Browser masquerade Chrome's TLS hello, HTTP/2 and WebSocket, with a static cover site on the same listener
Post-quantum security ML-KEM-1024 with X25519, Ed25519 with ML-DSA-87, and a fresh AES-256-GCM key for every data record
Fast Epoch rotation starts before the current epoch fills. The balanced preset kept about 95 % of plain TCP speed in emulator runs.
Built to embed One engine for the client, the server and the C library that apps and Android use

How it works

Application data is sealed by YTP/1, then wrapped in WebSocket, HTTP/2 and TLS. The opening follows a captured Chrome visit. Admission, authentication and service policy determine which traffic can pass.

Where YUME traffic goes On a direct route, yume reaches yumed over TLS and HTTP/2. The front door serves cover requests or admits a carrier for YTP/1 authentication. Authorized streams then reach their destinations. SOCKS5, forward or TUN TLS 1.3 + HTTP/2 valid proof OPEN a stream allowed cover request Application any program yume on your device Front door checks the proof YTP/1 session AUTH, then records Policy check service, destination Destination sees yumed's address Cover website static pages
Where your traffic goes. Ordinary visitors get the website. A client with the admission proof and its identity reaches the tunnel, and yumed opens only what its policy allows.
What each part does
yume
Collects traffic from applications and sends it to the server inside one long-lived connection that looks like a browser visiting a website.src/runtime/native_client_runtime.cpp
Front door
Serves ordinary HTTP/2 requests from the static site and promotes at most one stream per TLS connection after a fresh admission proof verifies.src/providers/h2_web_front_door.cppsrc/providers/ytp1_h2_admission.cpp
YTP/1 session
Both identities are proven with Ed25519 and ML-DSA-87, and the session keys mix X25519, ML-KEM-1024, the client's access PSK and the TLS connection.src/engine/session_engine.cppsrc/providers/openssl_security_provider.cpp
Policy check
Each stream names a service. yumed checks that this client may use it and that every address of the destination is allowed before it opens a socket.src/runtime/native_credentials.cppsrc/runtime/native_egress_policy.cpp
Cover website
The operator's own static site, loaded when yumed starts. There is no built-in fallback site.src/providers/cover_site.cpp
What wraps your data on the wire Application data is framed by YTP/1, sealed, then sent through the carrier envelope, WebSocket and HTTP/2 inside TLS 1.3. TCP to the server's port TLS 1.3 Chrome ClientHello HTTP/2 extended CONNECT stream WebSocket binary messages Carrier envelope 12-byte length header Sealed record AES-256-GCM, one-use key YTP/1 frame type, stream, length Your data stream bytes or a packet
What wraps your data on the wire. TLS 1.3 is the outside layer, and the YTP/1 record inside it has its own one-use key.
What each part does
Your data
What the application sent: bytes of a stream, or one whole packet for UDP and TUN.src/engine/session_engine.cpp
YTP/1 frame
A 12-byte header names the record type, the stream and the payload length. Frames are what both ends of a session exchange.src/ytp/protocol.hpp
Sealed record
Each data frame has a one-use AES-256-GCM key bound to direction, epoch and sequence. The REKEY_ACK control frame instead uses a candidate-root confirmation MAC inside TLS.src/providers/openssl_security_provider.cppsrc/engine/session_engine.cpp
Carrier envelope
Keeps each sealed record whole across partial reads and however WebSocket splits or joins messages.src/providers/h2_duplex_carrier.cpp
WebSocket
The carrier speaks ordinary WebSocket, with client frames masked as a browser masks them.src/stealth/websocket_codec.cpp
HTTP/2
One RFC 8441 CONNECT stream on a connection that has already loaded the cover site like a browser.src/stealth/h2_carrier.cpp
TLS 1.3
The outer encryption, opened with the ClientHello of the pinned Chrome release. An observer sees this layer and its sizes and timing.src/providers/tls13_secure_channel.cppsrc/stealth/tls_client_profile.cpp
TCP
One connection to the server's address, which anyone on the path can see.src/providers/asio_tcp_byte_channel_provider.cpp

Client and server

yume takes traffic from SOCKS5 (TCP and UDP), local forwards or a managed Linux TUN device. yumed serves the cover site and the tunnel on one port, and opens only the destinations its policy allows.

C library

The opt-in libyume runs the same endpoint inside another program: authenticated named streams, packet channels, and routed TCP and UDP.

Circuits

TCP connections can leave through two or three servers in one operator's cluster, with separate protection on every hop.

Modules

yumed hands a service's streams to a module program over a private UNIX socket. Chat, file and codec modules are planned on libraries that already exist.

The implementation status lists what each part is tested with.

Install

YUME builds from source on Linux x86-64. Add --tests to build the test executables.

Recommended

Build from source

ezbuild.sh prepares the checksum-pinned patched OpenSSL and nghttp2 and builds Release binaries into build/bin. It leaves the separate BaseFWX checkout alone.

Quick start YTP/1 development guide ezbuild.sh
Produces build/bin/yume and build/bin/yumed.
Linux amd64

Release artifacts

Binary releases are published on GitHub with checksums and a manifest. Until the first one, build from source.

  • yume-amd64-linux.tar.xz: client bundle with yume, yume-setup, yume-doctor, licensing documents, the quick start, and manifest.json
  • yumed-amd64-linux: daemon executable
client bundle daemon checksums
Debian

Packages

Debian metadata builds the native client and daemon packages. The service stays disabled until an operator installs and validates a kit.

  • yume: client, setup and doctor tools, manuals, and examples
  • yume-daemon: server, bootstrap configuration, locked service account, and hardened systemd unit
Packaging guide
Other surfaces

GUI, Android, and embedding

The Linux desktop GUI imports kits and starts, stops and watches clients through their control sockets. Build it with -DYUME_BUILD_GUI=ON. The Android client lives in its own repository and runs native YTP/1 through the C library's device bridge. Programs that embed the C library build against the same source tree, and its interface can still change between development versions.

C ABI Implementation status

Tunnel protection

Authentication, admission, and authorization are separate checks, and each one fails closed.

Layer YTP/1
Client identity A composite Ed25519 + ML-DSA-87 identity per client, and explicit trust in the server's composite identity. Both signatures must verify.
Key establishment ML-KEM-1024 + X25519 + a distinct 32-byte access PSK per client identity, with roles, identities, transcript, capabilities, parameters, and the TLS exporter bound into the key schedule.
Record layer One-use directional AES-256-GCM keys. The default epoch allows 1 MiB or 512 records, with a 500 ms send lifetime. Peers can agree on a larger epoch. Rotation starts halfway to a limit. Data waits if that limit is reached before confirmation. Streams and the connection have credit and bounded allocations.
Policy surface No security modes and no suite negotiation. Named service capabilities are authenticated, and every OPEN is authorized and bounded on its own.
Carrier Persistent TLS 1.3 + HTTP/2 + WebSocket on one connection, shaped by one immutable captured browser profile. A default-off capability in the pinned OpenSSL reproduces the profile's ClientHello structure.
Admission and cover An exporter-bound, replay-protected HMAC proof promotes one HTTP/2 stream to a carrier. Requests that fail admission stay in cover handling: GET and HEAD serve static routes, other methods get a fixed 405. TLS and resource refusals are described in the stealth reference.

yumed ends the tunnel, so it knows which client connected and where its traffic goes. HTTPS inside the tunnel keeps page content between the app and the site, as it does on any network. The threat model shows what each party can see, and the stealth model covers the browser profile and the captures behind it.

Build, provision, connect

The quick start walks through these steps. Credentials are owner-only files, and a client bundle must move to its machine through a trusted channel.

01

Build

Clone the tree and run ezbuild.sh.

02

Provision

yume-setup writes a server and client kit: identities, access PSK, admission key, TLS material, configuration, and a cover site.

03

Serve

yumed serves the cover site and the authenticated tunnel on one listener.

04

Connect

The client offers SOCKS5, local forwards, or a managed Linux TUN.

Build

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

Provision

./build/bin/yume-setup init \
    --host yume.example.com --port 8443 \
    --output ~/yume-kit --client-name laptop

Server

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

Client

./build/bin/yume --config ~/yume-kit/client/yume.json
curl --socks5-hostname 127.0.0.1:1080 https://example.com/

Before you open a server to the public, give it your own cover site and a certificate for its domain. The operations guide lists what to publish to its users.

Port 443 needs CAP_NET_BIND_SERVICE, which the packaged service grants and nothing more. Cloudflare in HTTP mode terminates TLS and breaks YUME. Use Spectrum or another TCP passthrough if you front the daemon with it.

Verify release files

The release workflow requires SHA-256 checksums and detached GPG signatures. It verifies both artifacts, the aggregate checksum list and the final manifest before uploading them.

Checksums

Verify with the per-artifact .sha256 file or the aggregate list.

Aggregate
sha256sum -c SHA256SUMS.txt

Signatures

The .sig sidecars cover both artifacts, the checksum list and the manifest.

GPG
gpg --verify yumed-amd64-linux.sig yumed-amd64-linux

Manifest

release-manifest.json records each artifact's component, OS, architecture, size, linkage, and SHA-256. Signatures travel in the .sig sidecars.

Live checksums for the current release

Read by task

Start with the quick start and the operations guide. The YTP/1 development guide covers build options, setup tools, embedding, and verification gates.

Start here

Quick start Build, provision, and connect the native YTP/1 client and daemon. Read YTP/1 development guide Build options, schema-1 kits, the native runtimes, managed TUN, embedding and verification gates. Read YUME explained How yume and yumed carry traffic: the connection, the keys, streams and policy, and what stays visible. Read Why YUME Internet freedom, the dream behind the name, and YUME's security, stealth and speed priorities. Read Stealth transport Browser-shaped TLS, the HTTP/2 carrier, the cover site, and the remaining differences. Read YTP/1 threat model Session protection, endpoint trust, metadata visibility and resource bounds. Read

Operating

Operations Provisioning, service deployment, client identities, limits, release verification and troubleshooting for native yume and yumed. Read Configuration Every key of the schema-1 configuration that yume and yumed read, with its role, bounds and meaning. Read Desktop GUI The yume-gui window: importing kits, starting and stopping tunnels, and what each page shows and why. Read Packaging Local installs, man pages, and the Debian package split. Read Preventing SOCKS bypass Browser proxy settings, route checks, and what a SOCKS proxy cannot enforce. Read Diagnostics Timing helpers, benchmark probes, compiler warnings, sanitizers and fuzzing for native builds, and what each result can show. Read Transport profiles How a captured browser and server identity enter the immutable registry. Read

Internals and status

Source map Where each part of the native runtime lives, how data and keys move through it, and which checks enforce the layers. Read YTP/1 architecture Native component ownership, dependency direction, and runtime boundaries. Read Experimental C ABI The experimental C interface for embedding YUME: lifetimes, statuses, symbols and freeze gates. Read Modules Programs that serve a stream service: configuration, the systemd units, what the program receives, the connection header and the trust boundary. Read Control socket The owner-only local socket where yume and yumed report their state and take requests, and the rules that let the GUI and later tools extend it. Read YTP/1 protocol The canonical transport kernel, native composition and qualification boundaries. Read Relay channel The end-to-end channel two YUME users run through a relaying server: handshake, records, ratchet and rekey. Read Sealed kit The one-file format that carries a client kit to another device, opened with a generated code. Read Cluster links The signed server list, the peer store and the links that make one operator's yumed servers a cluster. Read Circuits Cells, the per-hop handshake, layered encryption and relay messages of the circuits that carry a client's traffic through two or three cluster servers. Read Implementation status What exists, what has focused tests, and what still blocks a stable release. Read

Get help

Issues

Bug reports and feature requests on GitHub.

License

GNU Affero General Public License v3 or later.

Discord

FixCraft community chat.

Credits

F1xGOD
Founder & CEO, FixCraft, Inc.
Author. Lead developer and designer of Yume and BaseFWX.
Codex
Helpers
Code review, implementation, testing, and documentation.
Claude
Helpers
Code review, implementation, testing, and documentation.

Components by consumer

Native transport library 7 components
OpenSSL
Apache-2.0 + YUME patch AGPL-3.0-or-later
TLS 1.3 and every cryptographic primitive of the connection, with YUME's patch for the browser's handshake shape.
Boost
BSL-1.0
Asynchronous networking and timers.
nghttp2
MIT
HTTP/2 framing of the carrier.
nlohmann/json
MIT
Reading the configuration.
zlib
Zlib
Certificate compression in the TLS handshake.
Zstandard
BSD-3-Clause
Certificate compression in the TLS handshake.
Brotli
MIT
Certificate compression in the TLS handshake.
Linux client and daemon 1 component
libsystemd
LGPL-2.1-or-later
Linux managed TUN and resolver integration.
Desktop interface 1 component
Qt 6
LGPL-3.0-only / GPL-3.0-only / commercial
Desktop interface.
Android application 5 components
BaseFWX
LGPL-3.0-or-later
Wraps this app's stored data under the optional app-data password.
Bouncy Castle
MIT
Primitives BaseFWX's Java runtime uses.
Jetpack Compose
Apache-2.0
Declarative UI toolkit that renders every screen in this app.
AndroidX / Material 3
Apache-2.0
Android application and Material 3 interface components.
kotlinx.coroutines
Apache-2.0
Structured concurrency in the VPN service.
Optional Android ML Kit build 1 component
Google ML Kit (optional)
Google APIs Terms of Service
On-device translation for languages without a maintained translation.