flue

module

v0.9.4 Latest Latest Go to latest Published: Aug 20, 2026 License: MIT

Details

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

Repository

github.com/karnstack/flue

Links

Open Source Insights

README ¶

flue

Continue your Claude Code and Codex sessions on any screen.

flue.sh · setup · how it works · remote access · faq

Start on your laptop. Check in from your phone or iPad. Pick up again at your desk. The shell stays on the machine; flue moves the view.

A small Go daemon holds the shells and their scrollback, and a web app draws them. Closing the tab does not kill a session. It only detaches it: the agent keeps working, the build keeps running, the SSH session stays up, 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 doing.
One keystroke to any of them. ⌘K, or Ctrl+Shift+K anywhere, opens every session on every machine. The highlighted row shows its own last fourteen lines, so you can see which one is the build. Ctrl+Shift+1 to 9 jumps to a pinned session.
Reachable from anything you own. Pair a phone with a QR code, once for the whole fleet. Two devices on one session mirror live, and the size follows whichever view you are using.
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 and is 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 cannot be turned on, which happens in some containers, flue enable warns you and names the command to run. Everything after that happens in the browser.

Recommended setup

One relay, every machine joined to it, every device paired once.

Install flue and run flue enable on every machine that runs work: the laptop, the desktop, the Pi, the VPS.
Run flue relay setup once, on one machine. Running it again does not add a relay, it replaces the one you have: every machine then has to re-join with the newly printed line, and every device has to pair again.
Run the flue relay join line it prints on every other machine.
Pair each phone or tablet once, from a QR code. That pairing covers the whole fleet, so there is no second ceremony per machine. It is per browser, so Safari and Chrome on one iPad pair separately.

Long jobs belong on a machine that stays on. A sleeping laptop's sessions are not lost, but nothing runs until it wakes.

The full version is at flue.sh/docs/setup.

Sessions outlive flue

Every session runs in its own small holder process, not inside the daemon. Updating flue, restarting it, even the daemon crashing outright: the shells and agents keep running, and the next daemon picks them back up with their scrollback where you left it. A machine reboot is the one thing that ends a session, and even then flue brings it back with its history, a fresh shell, and the command that resumes the agent conversation it was in.

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 listens on loopback and nothing else, so reaching it from somewhere else 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 plan. The same deploy is a card on the UI's Remote screen. One relay fronts every machine you own, and pairing a device covers the whole fleet rather than one machine.

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

Released and in daily use. v0.5.1 is the current release, brew install karnstack/tap/flue gets it, and the whole of it works: the local terminal, the login service, the fleet-wide sessions list, pairing, and the Cloudflare relay. The relay has been through its manual end-to-end gate (docs/RELAY.md) against a real account, with a phone on a different network paired to it and a second machine joined to the same relay. There is a recording of that run at flue.sh/docs/setup.

It is 0.x, which means what it usually means: commands, flags and the config file can still change between releases, and an upgrade may ask something of you. 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

MIT

Directories ¶

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

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
agentstore Package agentstore reads the conversation transcripts that coding agents — Claude Code, Codex, Pi — keep under the user's home directory, and serves them back as one normalized shape: a summary per session, pages of messages, and search hits.	Package agentstore reads the conversation transcripts that coding agents — Claude Code, Codex, Pi — keep under the user's home directory, and serves them back as one normalized shape: a summary per session, pages of messages, and search hits.
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.
holder Package holder runs one session in its own process, which is the whole of how sessions outlive the daemon: the pty master, the child, and the scrollback ring live here, and the daemon holds nothing a restart can lose.	Package holder runs one session in its own process, which is the whole of how sessions outlive the daemon: the pty master, the child, and the scrollback ring live here, and the daemon holds nothing a restart can lose.
holdwire Package holdwire is the protocol between the daemon and a session holder: framing here, message shapes in msg.go.	Package holdwire is the protocol between the daemon and a session holder: framing here, message shapes in msg.go.
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.
session
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.
wire
relay 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.
web 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.