Self-hosted, ephemeral, end-to-end encrypted file transfer between your own devices. Think AirDrop — but cross-platform, self-hosted, and accessible from any browser.
> Self-hosted — deploy your own instance, see [Self-hosting](#self-hosting) below.
---
## What it is
flit solves a specific, annoying problem: getting a file from one of your devices to another right now, with no friction and nothing left behind on a server.
It is deliberately not a replacement for [Zipline](https://github.com/diced/zipline) or similar tools — those are great for "upload once, share via link." flit is for point-to-point transfers between devices you own: desktop to phone, homelab box to laptop, anything to anything.
- No accounts. No upload limits. No files touch a server disk.
- Works across networks (home WiFi ↔ mobile data) via a self-hosted TURN relay.
- Encrypted end-to-end with keys that never leave your devices.
- Remembered devices reconnect directly — no QR re-scan, no invite link.
- Multi-file send: select multiple files at once, each offered and accepted independently.
- Auto-downloads on the receiver side — no "click to save" step.
- In-app QR scanner (Chrome/Android) — scan the sender's QR without leaving flit.
- Android share sheet integration — "Share → flit" works from Photos, Files, any app.
Direct WebRTC P2P ──────────────────────── (preferred)
TURN relay (coturn) ─────────────────────── (fallback, still E2E encrypted)
```
Three components:
**Signaling anchor** — a lightweight Go WebSocket server (reused from [waste-go](../waste-go)). It brokers the WebRTC handshake: peers join a room by hashed name, exchange SDP offers/answers and ICE candidates through the anchor, then the anchor steps out of the way. No file data ever passes through it.
**TURN relay** — a coturn instance used as a fallback when direct peer-to-peer ICE fails (common across mobile networks and CGNAT). Data is end-to-end encrypted before entering the relay — coturn sees only ciphertext.
**Clients** — a PWA (primary) and a Go CLI (headless/homelab).
### Security model
Each device generates an **Ed25519 keypair** on first run. The hex-encoded public key is the device's permanent identity (`id`). This identity is stored in `localStorage` (PWA) or `~/.flit/` (CLI) and never leaves the device.
Pairing uses [yaw/2.1](PROTOCOL.md) forward-secret signaling, trimmed for flit's 1:1 ephemeral use case:
1. Connecting peers exchange **ephemeral X25519 keys** (`ekey`) signed with their Ed25519 identity keys over the sealed signaling channel — this is what actually authenticates "the device on the other end is who the QR said it was."
2. Once the WebRTC data channel opens, each side sends a **`hello`** message confirming its identity, plus a best-effort signature binding it to the session's DTLS fingerprint when both sides report that fingerprint under a hash algorithm flit can parse. `verified` status rests on step 1 (the authenticated sealed exchange) and `hello.id` matching it — not on the fingerprint signature, which different WebRTC stacks may report under different hash algorithms (WebKit: sha-512, Chromium/pion: sha-256) and so can't be relied on to match even between two legitimate peers.
3. File data flows over the WebRTC data channel — encrypted by DTLS, with the identity already confirmed by step 1.
The anchor never sees plaintext message content — it only routes sealed (encrypted) blobs by peer id and hashed room name.
### Pairing flows
**Ephemeral (QR)** — for first-time pairing or one-off transfers to unrecognised devices:
1. Sender opens flit → "Invite new" → "Show QR to pair." A 128-bit random room code is generated and encoded in a `flit:` invite string, displayed as a QR.
2. Receiver scans the QR using the in-app scanner ("Scan QR") or pastes the `flit:` string manually → "Join."
3. Both peers connect to the anchor under the hashed room name, complete the E2E handshake, and exchange files.
4. After connecting, either side can tap "Remember this device" and assign a nickname ("home", "phone") to the peer's identity.
**Trusted device (direct reconnect)** — for devices that have been previously paired:
1. flit opens to the "Known devices" screen by default (falls back to "Invite new" if none exist yet).
2. Tap **Connect** next to a remembered device — no QR, no invite string.
3. Both sides independently compute the same deterministic room name from their two peer IDs (`flit-pair:<sorted(idA, idB)>` in `pwa/src/pairing/ephemeral.ts`), join it pinned to each other's identity, and the handshake completes automatically.
The room is pinned to the trusted peer's identity — any other device that somehow joins the same derived room is silently ignored. Trusted peers can be renamed or forgotten at any time from the Known devices list.
---
## Clients
### PWA
The primary client. Runs in any Chromium-based browser and is installable as a PWA on Android home screen. Once installed, it registers as a **Web Share Target** — "Share → flit" in any Android app's share sheet will open flit with the file pre-loaded, ready to send after pairing.
Features:
- Known devices tab (direct reconnect) and Invite new tab (QR / paste)
- In-app QR scanner via native `BarcodeDetector` API (no library, Chrome/Android)
- Multi-file send with per-file accept/reject on the receiver, "Accept all" when multiple arrive simultaneously
- Real-time send and receive progress bars
- Auto-download on receipt — files save immediately without a manual tap
`flit daemon` is an always-on receiver — it stays connected to a list of trusted peers and automatically accepts any file they send, saving to a configured directory. Useful for a homelab node that acts as a drop-point: send from phone or laptop, file appears on the home box without any interaction.
id = "aabbccddeeff..." # hex Ed25519 pubkey — from PWA Known devices list
label = "phone" # or from "peer connected" line in flit send output
[[peers]]
id = "112233445566..."
label = "laptop"
```
Copy `cli/daemon.toml.example` to `~/.flit/daemon.toml` to get started. The daemon runs one goroutine per peer, reconnects automatically with exponential backoff (2s → 30s cap) if the peer drops or the anchor restarts, and logs all activity to stdout — suitable for a tmux session or systemd unit.
**Topology note:** the daemon is just a third peer with its own identity. If you run it on a home box and trust it from both your phone and laptop, all three devices can reach each other directly — phone→laptop still works without the home box involved. The daemon adds an always-on rendezvous point, not a relay.
**Bootstrapping:** to get a peer's `id`, pair once via QR (`flit send` / PWA "Invite new") and copy the hex ID from the "peer connected" log line, or read it from the PWA's Known devices list after tapping "Remember this device."
`flit watch` is the send-side sibling of `flit daemon`: it watches one or more local folders and automatically pushes new or changed files to a specific trusted peer — no manual `flit send`, no QR, no per-file interaction. It's **one-way sync only** (source → destination, push only) — deliberately not a general bidirectional sync tool, and it never propagates deletes.
The receiving side needs no changes: an already-running `flit daemon`, configured with the watcher's device as a trusted peer, already does the right thing on receipt.
Config lives at `~/.flit/watch.toml`:
```toml
signal_url = "wss://your-anchor.example.com/ws"
turn_url = "" # optional
turn_secret = "" # optional
[[watch]]
dir = "/home/user/backups/documents"
peer_id = "<hex Ed25519 pubkey of the destination device>"
stable_after = "10s" # optional quiet period before considering a file ready
```
Multiple `[[watch]]` blocks are allowed — different folders can go to different peers, or the same peer (entries sharing a `peer_id` share a single connection).
Copy `cli/watch.toml.example` to `~/.flit/watch.toml` to get started. Notes on behavior:
- **Startup reconciliation** — on start, before subscribing to filesystem events, `flit watch` walks each `dir` and diffs it against local state, so anything that changed while the watcher wasn't running gets picked up (not just live events going forward).
- **Debounce (`stable_after`)** — a file is only considered ready to send after this quiet period has passed since its last write, so a large file being actively written isn't offered mid-write.
- **State tracking** — one JSON state file per `[[watch]]` entry lives in `~/.flit/watch-state/`, recording what's been sent. If a send fails partway (peer disconnects mid-transfer), the file is retried on the next successful connection — no separate retry logic needed. Losing this state is harmless (worst case: the whole directory gets re-sent) but not something to engineer around.
- **`flit watch --dry-run`** walks the configured directories and prints what *would* be sent, without connecting to anything — use it to sanity-check a new `watch.toml` before it goes live.
- **`pattern` should be as narrow as your use case allows.** `*` is the default if omitted, but an unconstrained watch on a broad directory turns "sync my documents" into "sync everything that ever lands in this tree." There's no per-file confirmation in watch mode — the directory and pattern in `watch.toml` are the only safety knob.
- Reconnects with the same exponential backoff (2s → 30s cap) as daemon mode, and reuses the same trusted-peer identity model — a `peer_id` here is the same kind of already-known device as anything in the PWA's Known devices list or `daemon.toml`.
flit has no server of its own. The PWA is a static file bundle served by `npx serve`. For signaling and TURN relay it requires a running [waste-go](https://repo.explewd.com/explewd/waste-go) anchor.
### Deploy scripts
The deploy scripts contain your SSH target and are gitignored — create them locally from these templates:
**`deploy-pwa.sh`** — build and rsync `pwa/dist/` to the host:
```bash
#!/usr/bin/env bash
set -euo pipefail
HOST="user@your-host.example.com"
REMOTE_DIR="~/flit-www"
echo "→ building PWA…"
"$(dirname "$0")/build-pwa.sh"
echo "→ syncing to $HOST:$REMOTE_DIR"
rsync -azv --delete \
--exclude='config.js' \
pwa/dist/ "$HOST:$REMOTE_DIR/"
echo "✓ done"
```
**`serve-pwa.sh`** — (re)start `npx serve` on the host:
```bash
#!/usr/bin/env bash
set -euo pipefail
HOST="user@your-host.example.com"
REMOTE_DIR="~/flit-www"
REMOTE_LOG="~/flit-www.log"
REMOTE_PID="~/flit-www.pid"
PORT=3002 # pick a free port; point your reverse proxy here
Your reverse proxy should forward `flit.<domain>` → `localhost:<PORT>` (the port chosen above).
### CI / releases
`.gitea/workflows/build.yml` builds the PWA on `v*` tag push and publishes `flit-pwa.tar.gz` as a Gitea release artifact. Requires a `RELEASE_TOKEN` secret in the repo settings.
The PWA reads its anchor URL from `public/config.js` at runtime. The CLI reads `FLIT_SIGNAL_URL` from the environment. Both are gitignored/unset by default — you supply your own anchor.
---
## Protocol
flit speaks a trimmed subset of [yaw/2.1](PROTOCOL.md). Dropped vs. waste-go: chat, presence, multi-peer mesh, file browsing. Kept: Ed25519 identity, forward-secret `ekey` handshake, `hello` verification, `file-offer`/`file-accept`/`file-cancel`, chunked binary DataChannel transfer.
---
## Changelog
### Scaffolding
- Repo scaffold: PWA (React/TS/Vite) + Go CLI skeleton
- Go CLI: `flit send` / `flit recv`, Ed25519 identity in `~/.flit/`, terminal QR output
- PWA: ephemeral QR pairing, yaw/2.1 signaling, WebRTC file transfer, Web Share Target manifest
- RTCPeerConnectionState surfaced in UI (`checking` / `connected` / `failed`) — previously stuck silently on "Connecting…"
- Sender-side progress events and progress bar (fix: synchronous chunk loop blocked React renders — added `setTimeout(0)` yield per chunk)
-`peerId` now set at connection time, not only on first file offer — fixed "Remember this device" silently doing nothing
### Trusted devices / known peer reconnect
- Persistent keyring (`pwa/src/pairing/keyring.ts`) — Ed25519 peer IDs stored in `localStorage` with user-assigned nicknames
-`pairRoomName(idA, idB)` — deterministic shared room derived from sorted peer IDs; both sides compute independently, no QR needed
- Known devices tab: default view when trusted peers exist; Connect / Rename / Forget per device
- Nickname prompt on "Remember this device" (previously auto-used key prefix)
-`connected` event now carries `peerId` so the keyring button works immediately after handshake, not only after a file offer
### Multi-file and UX
- Multi-file receive: offer queue (previously a single slot — second offer replaced first); "Accept all (N)" button when multiple arrive simultaneously
- Auto-download on receipt via programmatic `<a>.click()` — no manual tap required
- In-app QR scanner using native `BarcodeDetector` API (no library); camera overlay with cancel; graceful fallback message on unsupported browsers
- Received files list retained below the auto-download as a fallback link
### Visual design
- Full restyle to terminal aesthetic matching waste-go's visual identity: `#080808` bg, `#00e87a` green accent, JetBrains Mono throughout
-`manifest.json`: fixed missing PNG icon references (replaced with SVG), corrected `theme_color` from blue → green
- Apple PWA meta tags added (`apple-mobile-web-app-capable`, status bar style, title)
- Progress bars with green glow, `> flit.` monospace header, `@ nickname` device labels, `// comment` style hints
