loft

module

v1.0.4 Latest Latest Go to latest Published: Oct 16, 2026 License: Apache-2.0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/a3app/loft

Links

Open Source Insights

README ¶

loft

English · Русский

loft is an overlay that runs inside TLS. Streams are multiplexed over GET, WebSocket, HTTP/2, QUIC, or HTTP/3 and sealed with ChaCha20-Poly1305. On the public path the session looks like ordinary HTTPS, so it passes CDNs, reverse proxies, and TLS terminators. The session holds through short disconnects and packet loss.

Protocol loft/1.0. Share URI loft://. YAML kind: loft.

This repository is the open specification and a reference node plus clients (macOS app, Linux and macOS CLI). Software 1.0.4. A third party can implement loft from docs/protocol.md.

Operators

Typical use is operator access: a lab LAN from outside, a server fleet, site-to-site. Members present a browser-shaped ClientHello. If a middlebox rewrites the handshake, the session does not come up.

Download

Files from the latest GitHub Release. Dist uploads these names on every v* tag, so 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

Checksums: clients · node. macOS DMG is the menu-bar app (ad-hoc signed). CLI archives are loft, loft-front, loft-probe, loft-bench.

Protocol

application → SOCKS5 / TUN
    mux (Open / Data / Close / Dgram / Leave)
      ChaCha20-Poly1305
        get | ws | h2 | quic | h3
          TLS 1.3
            TCP 443 or UDP 443


docs/protocol.md	Wire protocol. Sufficient to implement a third-party client or node.
docs/architecture.md	Layout of this tree.
docs/guide.md	Build, configure, run, Debian.
docs/yandex-cdn_ru.md	Yandex Cloud CDN operator guide (RU).
docs/keenetic.md	KeeneticOS Entware client (OpkgTun). Catalog: clients/Keenetic/.
docs/ios.md	iOS Packet Tunnel client. Catalog: clients/iOS/.
docs/android.md	Android VpnService client. Catalog: clients/Android/.
docs/share.md	Import URI `loft://` and `.loft` files (one or several connections).

Repository

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

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

Tag vX.Y.Z (must match VERSION) runs GitHub Actions: tests, make dist, macOS DMGs arm64 and x86_64 (ad-hoc), and a Release. Manual: Actions → Dist.

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.

License

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

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
clients
go/cmd/loft command Command loft is the CLI client: config-driven GET/WS/QUIC outbound, SOCKS5, and optional TUN with kill-switch.	Command loft is the CLI client: config-driven GET/WS/QUIC outbound, SOCKS5, and optional TUN with kill-switch.
go/cmd/loft-bench command Command loft-bench repeats the macOS app connect path (front, SOCKS5, TCP probe) and measures mux/SOCKS throughput for GET and WS.	Command loft-bench repeats the macOS app connect path (front, SOCKS5, TCP probe) and measures mux/SOCKS throughput for GET and WS.
go/cmd/loft-front command Command loft-front is the GUI helper: GET/WS/H2/QUIC/H3 front, SOCKS5, and in-process or loft-priv TUN.	Command loft-front is the GUI helper: GET/WS/H2/QUIC/H3 front, SOCKS5, and in-process or loft-priv TUN.
go/cmd/loft-probe command Command loft-probe sends ICMP, TCP, UDP, DNS, HTTP, and HTTPS through loft mux or SOCKS5 without rewriting system routes or opening utun.	Command loft-probe sends ICMP, TCP, UDP, DNS, HTTP, and HTTPS through loft mux or SOCKS5 without rewriting system routes or opening utun.
go/inbound Package inbound is the loft client listener: SOCKS5, userspace TUN (ICMP/UDP/TCP), Darwin/Linux DNS and routes, optional overlay IPv6.	Package inbound is the loft client listener: SOCKS5, userspace TUN (ICMP/UDP/TCP), Darwin/Linux DNS and routes, optional overlay IPv6.
go/tools/wsprobe command Command wsprobe is a one-shot HTTP GET through a loft GET front.	Command wsprobe is a one-shot HTTP GET through a loft GET front.
mobile Package mobile is the shared Go session for iOS Packet Tunnel and Android VpnService.	Package mobile is the shared Go session for iOS Packet Tunnel and Android VpnService.
internal
cdn Package cdn holds vendor edge profiles on top of protocol fronts get/ws.	Package cdn holds vendor edge profiles on top of protocol fronts get/ws.
config Package config loads client.yaml and node config (YAML or switch-style commands).	Package config loads client.yaml and node config (YAML or switch-style commands).
crypto Package crypto seals mux with ChaCha20-Poly1305, proves membership with clockless HMAC (0x02) or a resume ticket (0x03), and derives the session key via HKDF-SHA256 (info "loft-v1").	Package crypto seals mux with ChaCha20-Poly1305, proves membership with clockless HMAC (0x02) or a resume ticket (0x03), and derives the session key via HKDF-SHA256 (info "loft-v1").
identity Package identity is the member key: lt_ plus 48 hex characters (24 bytes).	Package identity is the member key: lt_ plus 48 hex characters (24 bytes).
mux Package mux multiplexes streams and datagrams over AEAD-protected frames after Status.	Package mux multiplexes streams and datagrams over AEAD-protected frames after Status.
netconf Package netconf is Loft overlay 1.0 network.conf: members, overlay IPs, leases, Cisco-style ACL, IPAM, DNS policy, session timers, managed routes and VLANs.	Package netconf is Loft overlay 1.0 network.conf: members, overlay IPs, leases, Cisco-style ACL, IPAM, DNS policy, session timers, managed routes and VLANs.
protect Package protect marks VPN process sockets so they use the physical path (Android VpnService.protect).	Package protect marks VPN process sockets so they use the physical path (Android VpnService.protect).
sstp
startup Package startup scans loft node and overlay config written as switch-style commands (Keenetic / D-Link / Cisco extended ACL).	Package startup scans loft node and overlay config written as switch-style commands (Keenetic / D-Link / Cisco extended ACL).
transport Package transport implements Loft 1.0 fronts, TLS camouflage, decoy splice, borrowed-cert mask, CONNECT splice, and client dialing.	Package transport implements Loft 1.0 fronts, TLS camouflage, decoy splice, borrowed-cert mask, CONNECT splice, and client dialing.
trojan
version Package version holds the program release (injected from VERSION, currently 1.0.4 when built) distinct from protocol 1.0 (0x0100).	Package version holds the program release (injected from VERSION, currently 1.0.4 when built) distinct from protocol 1.0 (0x0100).
vless
wire Package wire is loft overlay protocol 1.0 (0x0100): Hello/Status handshake, mux frames, signed roster/lists, and fleet control.	Package wire is loft overlay protocol 1.0 (0x0100): Hello/Status handshake, mux frames, signed roster/lists, and fleet control.
xtls
server
cmd/loft-node command Command loft-node is the overlay node daemon: controller or relay.	Command loft-node is the overlay node daemon: controller or relay.
origin Package origin serves the node's public HTTPS origin.	Package origin serves the node's public HTTPS origin.
origin/cover Package cover serves the embedded TLS/QUIC cover site shown to ordinary browsers.	Package cover serves the embedded TLS/QUIC cover site shown to ordinary browsers.