README
¶
flue
Your work shouldn't stop when you close the laptop.
flue.sh · how it works · remote access · faq
Builds, agents and SSH sessions keep running on the machine that owns them, and you pick any of them back up on any device you have. A small Go daemon holds the shells and their scrollback; a web app renders them. Closing the tab detaches rather than kills, and reattaching replays what you missed.
- Sessions outlive the tab. Close it and the build keeps running.
- One list, every machine. Name, tag, pin, group and search the whole fleet from one place. Hover a session to see what it is actually doing.
- Reachable from anything you own. Pair a phone with a QR code. Two devices on one session mirror live, and the phone's 40 columns don't shrink the laptop.
- No hosted service. Remote access runs through a relay you deploy into your own Cloudflare account, end-to-end encrypted with the daemon's key pinned at pairing. flue.sh is a landing page, never part of the data path.
One static Go binary. macOS, Linux, WSL. No Node, no Python, no toolchain.
Install
brew install karnstack/tap/flue # or: curl -fsSL https://flue.sh/install.sh | sh
flue enable
flue enable installs a login service, starts the daemon, and opens the UI.
On Linux it also runs loginctl enable-linger, so the daemon — and your
sessions — survive your last logout; if lingering can't be enabled (some
containers refuse it), flue enable warns and names the command to run.
Everything after that happens in the browser.
The CLI
flue enable # install the login service, start the daemon, open the UI
flue disable # remove it
flue status # daemon, login service, and session diagnostics
flue open [path] # spawn a session here, handy from a shell prompt
flue relay setup # deploy a relay to your own Cloudflare account
flue relay join # point this machine at a relay another machine deployed
flue relay status # show the configured relay
flue relay update # redeploy this release's relay; secret and pairings kept
flue relay address # repoint this machine at a custom domain on the same relay
flue relay leave # take this machine off its relay; the Worker stays deployed
flue serve # run the daemon in the foreground, no login service
flue update # download the newest release, swap this binary, restart the daemon
flue version # print the version (also --version, -v)
Remote access
The daemon binds loopback and nothing else, so reaching it from elsewhere is opt-in and takes one command:
flue relay setup # machine 1: paste a Cloudflare token
flue relay join wss://<your-relay> --secret <...> --fleet <...> # every other machine
That deploys a Worker and this web app into your own Cloudflare account, on the free tier. The same deploy is a card on the UI's Remote screen. One relay fronts every machine you own; pairing is per machine, once per browser, from the QR each machine shows.
What it deploys and what it costs is at flue.sh/docs/relay, with the operator-grade version in docs/RELAY.md. What a hostile relay origin could do despite the end-to-end encryption, which is the honest version because the browser loads its JavaScript from that origin, is in the FAQ and at length in docs/faq.md.
Status
Pre-1.0, and honest about it. The local terminal, the login service, the fleet-wide sessions list and the end-to-end pairing all work. The Cloudflare relay is built and deployable but has not been through its manual end-to-end gate against a real account (docs/RELAY.md), so treat it as ready to try rather than ready to rely on. Known rough edges live in docs/FOLLOW-UPS.md.
flue is open source and always free.
Building and developing
mise install # go, node, pnpm, pinned in mise.toml
make build # web UI + relay Worker, embedded, into bin/flue
make test
The dev loop, the dev/prod split, and working on the relay are in
docs/DEVELOPMENT.md. The landing site is its own package
under site/, and make site-dev runs it.
License
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
flue
command
Command flue runs the flue daemon and opens terminal sessions in the browser.
|
Command flue runs the flue daemon and opens terminal sessions in the browser. |
|
internal
|
|
|
cloudflare
Package cloudflare is a small client for the parts of the Cloudflare v4 REST API that `flue relay setup` needs: verifying a user's API token, listing the accounts it can reach, and deploying the relay Worker — script, Durable Object, static assets and all — into the account they choose.
|
Package cloudflare is a small client for the parts of the Cloudflare v4 REST API that `flue relay setup` needs: verifying a user's API token, listing the accounts it can reach, and deploying the relay Worker — script, Durable Object, static assets and all — into the account they choose. |
|
config
Package config locates and manages flue's on-disk configuration, including the loopback authentication token.
|
Package config locates and manages flue's on-disk configuration, including the loopback authentication token. |
|
crypto
Package crypto owns flue's Noise IK handshake, the secure channel framing, and the key material on the daemon side.
|
Package crypto owns flue's Noise IK handshake, the secure channel framing, and the key material on the daemon side. |
|
daemon
Package daemon wires sessions, the wire protocol, and a transport into an HTTP server.
|
Package daemon wires sessions, the wire protocol, and a transport into an HTTP server. |
|
fleet
Package fleet is the fleet key and the certificates it signs (spec/fleet-trust.md): one Ed25519 keypair per relay, held by every machine and never by the Worker, whose signatures are what let a device paired on one machine be trusted by every other.
|
Package fleet is the fleet key and the certificates it signs (spec/fleet-trust.md): one Ed25519 keypair per relay, held by every machine and never by the Worker, whose signatures are what let a device paired on one machine be trusted by every other. |
|
relaydeploy
Package relaydeploy is the one implementation of "put flue's relay into a Cloudflare account": the Worker module, the web bundle, the Durable Object migration, the secret, the workers.dev host.
|
Package relaydeploy is the one implementation of "put flue's relay into a Cloudflare account": the Worker module, the web bundle, the Durable Object migration, the secret, the workers.dev host. |
|
relaywire
Package relaywire defines the framing that crosses the daemon↔relay socket.
|
Package relaywire defines the framing that crosses the daemon↔relay socket. |
|
service
Package service installs and removes the flue login service: a launchd agent on darwin, a systemd user unit on linux.
|
Package service installs and removes the flue login service: a launchd agent on darwin, a systemd user unit on linux. |
|
transport/local
Package local implements the loopback transport: a listener bound to 127.0.0.1 and authenticated by a token file, an Origin allowlist, and a Host check.
|
Package local implements the loopback transport: a listener bound to 127.0.0.1 and authenticated by a token file, an Origin allowlist, and a Host check. |
|
transport/relay
Package relay is the daemon's leg of the Cloudflare relay: one outbound WebSocket to a Worker, and every browser that reaches this machine multiplexed over it.
|
Package relay is the daemon's leg of the Cloudflare relay: one outbound WebSocket to a Worker, and every browser that reaches this machine multiplexed over it. |
|
Package relaybundle carries the built relay Worker inside the flue binary, so that `flue relay setup` can deploy it into a user's own Cloudflare account with no Node, no wrangler, and no checkout — the same promise the embedded web app makes for the daemon's UI.
|
Package relaybundle carries the built relay Worker inside the flue binary, so that `flue relay setup` can deploy it into a user's own Cloudflare account with no Node, no wrangler, and no checkout — the same promise the embedded web app makes for the daemon's UI. |
|
Package web serves the built flue UI from the daemon binary, so there is no runtime dependency on Node or on any files beside the executable.
|
Package web serves the built flue UI from the daemon binary, so there is no runtime dependency on Node or on any files beside the executable. |