Remote Host (Codux Agent)

The headless Codux Agent (codux) is the non-GUI counterpart of the desktop app. Run it on any machine — a server, a spare Mac, a Linux box — and your desktop or phone connects to it over an end-to-end encrypted Iroh link to run that machine’s terminals, Git, AI sessions, and memory remotely. Everything runs against the host’s own data; the client just drives it.

One binary, codux, drives everything. It builds and runs on macOS, Linux, and Windows (x86_64 and arm64). PTYs use portable-pty (ConPTY on Windows), and transport / Git / AI are all platform-neutral.

Install

One-line installer (recommended)

On macOS or Linux, this grabs the right codux binary for your OS/arch and puts it on your PATH — no build toolchain required:

curl -fsSL https://raw.githubusercontent.com/duxweb/codux/main/apps/agent/scripts/install.sh | sh

Handy flags (pass them after sh -s --):

• --setup — run codux config + codux install right after installing
• --beta — install the newest build, including pre-releases
• --version <x.y.z> — pin an exact version
• --dir <path> — install to a specific directory
• --mirror <prefix> — prepend a download mirror when GitHub is slow
• --uninstall — remove the host (add --purge to also delete config, pairings, and logs)

To remove it later:

curl -fsSL https://raw.githubusercontent.com/duxweb/codux/main/apps/agent/scripts/install.sh | sh -s -- --uninstall

Manual download

Prefer to do it by hand (or on Windows)? Grab the codux-<os>-<arch> binary from Releases and put it on your PATH as codux. Or build from source:

cargo build -p codux-agent --release   # produces `codux-agent`

Set it up

codux config     # set it up (device name, relay)
codux install    # run as a startup service
codux qrcode     # show the pairing QR for your phone/desktop

The service installer targets launchd (macOS), systemd --user (Linux), and Task Scheduler (Windows), so codux install makes the host start at login and restart on failure.

Pair a device

1. On the host, run codux qrcode (or codux link to print the ticket as text).
2. On the desktop, open Settings → Remote → Connect and scan the QR or paste the ticket. On the phone, scan the QR.

Because reaching the host already requires the one-time Iroh ticket, pairing is auto-confirmed — the ticket is the gate. No credentials ever leave the host.

Need to preview a dev server running on the host? Use the Web Tunnel Browser available in Codux 2.0 and later.

Commands

Command	What it does
codux version	Print the version and protocol revision.
codux config	Interactive setup wizard. Writes codux.toml, reusing existing values as defaults. Steps: device name → relay network → (custom relay: URL + reachability check + optional auth).
codux start	Start the host in the foreground (banner + logs). Idempotent — if one is already running it prints where, instead of starting a second.
codux stop	Stop the running host.
codux status	Whether the host is running, since when, the node id, and how many devices are paired.
codux install	Register codux start with the OS service manager so it starts at login and restarts on failure.
codux uninstall	Stop and remove the service.
codux qrcode	Print the pairing QR in the terminal (starts the host first if needed).
codux link	Print the pairing ticket as text, to paste into the desktop’s “Connect” box.
codux update	Check GitHub Releases for a newer build, then download, verify, replace this binary, and restart the host.
codux device	Table of paired devices (id, name, type, last seen).
codux device:del <id>	Remove a paired device.
codux device:rename <id>	Rename a paired device.
codux device:clear	Remove every paired device.

Run codux <command> --help for details.

How it works

• Single instance. The running host holds an advisory lock (codux.lock); start and the pairing commands use it to detect “already running” rather than starting a second copy.
• Stable identity. host_id + host_token (generated once by config) seed the Iroh node identity, so the pairing ticket and every saved desktop’s reconnect target survive restarts. They are never rotated automatically.
• Auto-recovery. A desktop that drops and reconnects resumes the same host terminal sessions — the PTYs (and their running shells / AI) stay alive across a client disconnect.

Files

State lives in ~/.codux-agent (override with $CODUX_AGENT_DATA_DIR):

File	Purpose
codux.toml	Configuration (from codux config).
devices.json	Paired devices.
pair-ticket.json	The published pairing ticket.
status.json	Running daemon status (pid, start time, node).
codux.lock	Single-instance lock.
codux.log	Background daemon log.

Relay vs. host

The relay only helps two devices find each other and carries traffic when a direct path is unavailable — it never runs your terminal or sees decrypted content. The host (this codux agent, or your desktop app) is what actually runs the sessions. To run your own relay, see Self-host a Relay Node.