loft

README

English · Русский · 中文

A private overlay is described which is carried inside TLS 1.3. Application streams are multiplexed over GET, WebSocket, HTTP/2, QUIC, or HTTP/3 and are sealed with ChaCha20-Poly1305. On the public path the session is ordinary HTTPS, and may therefore be passed through a CDN, reverse proxy, or TLS terminator. Short disconnects and packet loss are tolerated: the mux is parked and later resumed, so that inner TCP is not torn down.

The protocol is loft/1.0. Connections are shared as loft://. YAML kind: loft.

This repository is the specification together with a reference node, a web panel, and clients (a macOS application and CLI tools for Linux and macOS). Software 1.0.24. A third party may implement loft from docs/protocol.md.

Contents

• Operators
• Download
• App
• Panel
• How it works
• Repository
• Build
• Support
• License

Operators

The intended use is operator access: a laboratory LAN reached from outside, a server fleet, or a site-to-site path. Members present a browser-shaped ClientHello. Should a middlebox rewrite the handshake, the session is not established.

Download

Binaries are published in the latest GitHub Release. Dist uploads these names on every v* tag, so that the links follow the current release.

	Apple Silicon / arm64	Intel / amd64
macOS app	DMG	DMG
macOS CLI	tar.gz	tar.gz
Linux CLI	tar.gz	tar.gz
Node	tar.gz · deb	tar.gz · deb
Panel	tar.gz · deb	tar.gz · deb

Checksums: clients · node · panel. The macOS DMG is the menu-bar application (ad-hoc signed). CLI archives contain loft, loft-front, loft-probe, and loft-bench.

App

The macOS client is a menu-bar application. The overlay is opened from it; several named connections may be kept; a loft:// link or a .loft file may be imported. SOCKS5 and TUN remain local.

Status	Connections

Panel

Web administration of one loft server: the node, its networks and members, IP addresses and upstream channels, domains with DNS records and certificates, mail, packages, and panel users. The aim is that a loft server may be installed and configured without files being edited by hand. Spec: server/panel.

How it works

flowchart LR
    subgraph Client["loft client"]
        App["SSH · browser · curl"] --> In["SOCKS5 / TUN"]
        In --> Mux["mux Open / Data / Close / Dgram"]
        Mux --> Seal["ChaCha20-Poly1305"]
        Seal --> Front["get · ws · h2 · quic · h3"]
    end
    Front -->|"TLS 1.3 HTTPS"| Edge["CDN / reverse proxy"]
    Edge --> Node["loft-node"]
    Node --> Dest["lab · fleet · site"]

1. Applications speak to a local SOCKS5 or TUN listener. That listener is held by Holder while the front is rotated.
2. Streams are carried on one mux and are sealed with ChaCha20-Poly1305.
3. On the public path the session is ordinary HTTPS, so that a CDN or reverse proxy may sit in front of the node.
4. A short disconnect causes the mux to be parked for gap_hold_ms (8 s by default). Resume is performed with a fresh 0x02 and the same instance_id; inner TCP is left standing.

docs/protocol.md	The wire protocol. A third-party client or node may be implemented from it.
docs/architecture.md	Layout of this tree.
docs/guide.md	Build, configuration, operation, Debian.
docs/yandex-cdn_ru.md	Yandex Cloud CDN operator guide (RU).
docs/keenetic.md	KeeneticOS Entware client (OpkgTun). Catalog: clients/Keenetic/.
docs/mikrotik.md	RouterOS 7 container client. Catalog: clients/MikroTik/.
docs/ios.md	iOS Packet Tunnel client. Catalog: clients/iOS/.
docs/android.md	Android VpnService client. Catalog: clients/Android/.
docs/aurora.md	Aurora OS ConnMan client. Catalog: clients/Aurora/.
docs/share.md	Import URI loft:// and .loft files (one or several connections).

Repository

docs/             protocol, architecture, guide
docs/brand        mark and icons
internal/         wire, mux, crypto, transport, overlay
server/           loft-node (controller or relay)
server/panel      loft-panel web admin
clients/go        loft, loft-front, loft-probe
clients/macOS     menu-bar app (launches loft-front)
clients/Keenetic  Entware / OpkgTun (plan and mock)
clients/MikroTik  RouterOS 7 container (image + .rsc)
clients/iOS       Packet Tunnel (thin host + appex)
clients/Android   VpnService (thin Java host)
clients/Aurora    ConnMan overlay (thin QML host)
clients/mobile    shared Go engine (gomobile bind)

Build

Go 1.24+. From the repository root:

make test
make node       # ./loft-node
make client     # dist/clients/go/loft
make macos      # dist/clients/macOS/loft.app
make macos-dmg  # dist/clients/macOS/loft-*-macos-<arch>.dmg
make macos-dmgs # both arm64 and x86_64 DMGs (CI)
make dist       # node tarballs/.deb + CLI archives

A tag vX.Y.Z matching VERSION runs GitHub Actions: tests, make dist, macOS DMGs for arm64 and x86_64 (ad-hoc), a Release, and a pkg.go.dev ping. The same Dist workflow may be started by hand from Actions.

export LOFT_TOKEN='change-me-long-random'
./loft-node -c server/configs/server.yaml -dir /var/lib/loft
./dist/clients/go/loft -c clients/go/configs/client.yaml
ALL_PROXY=socks5://127.0.0.1:1080 curl https://example.com

Debian package and installer: server/debian/README.md.

Support

Work on an open internet is not free. Sponsorship is accepted so that the protocol, the node, and the clients may be kept independent.

	Network	Address
Bitcoin	Bitcoin	bc1q3q8vzxta0yegvwkgth44a0n2ee8d9kjtjs738t
Ethereum	Ethereum	0xEfBF2e1C8B76B6033ab00199Bdf36671ed0Dba3A
Tether	Ethereum (USDT ERC-20)	0xEfBF2e1C8B76B6033ab00199Bdf36671ed0Dba3A
TRON	TRON	TQq2CGEZ7rTE7RqA6rhh2H8j24qdUqd5Jx
Tether	TRON (USDT TRC20)	TQq2CGEZ7rTE7RqA6rhh2H8j24qdUqd5Jx
Litecoin	Litecoin	ltc1qq93zr9pjst9fy732qjuy0pltze4x4llcv30w79
Zcash	Zcash (transparent)	t1RCtApkwLxjuG2dmR7SdnHSVR1Xrx2c6Bk

ETH and USDT ERC-20 are received at the same Ethereum address. TRX and USDT TRC20 are received at the same TRON address. USDT must be sent on the network of that row. Details are given in SUPPORT.md.

License

Apache License 2.0. loft/1.0 may be implemented from docs/protocol.md without a fee.