Get started — Vox Lux

01. Install Vox

Prebuilt releases support Apple Silicon macOS, Intel macOS, and x86_64 Linux. The installer checks the release record, size, and SHA-256 before placing the binary in ~/.local/bin. On macOS, it also requires the Developer ID signature and notarization checks to pass.

curl -fsSL https://voxlux.us/install.sh | sh

voxlux.us/install.sh redirects to GitHub’s v0.2.10 installer, unchanged. That script uses GitHub’s latest stable release record to select the binary; GitHub remains the source of truth.

You can read the installer before running it, or browse the release assets. No sudo is required.

Build from source instead

Install Rust through your usual toolchain manager first. The repository pins the Rust version it needs.

git clone --branch v0.2.10 --depth 1 https://github.com/robertelee78/vox.git
cd vox
cargo build --release --locked -p vox-tui

The binary is target/release/vox. A source build is updated by rebuilding it, not by vox update.

02. Create your identity

vox

Follow the first-run prompt to create an identity protected by your identity passphrase. Vox generates your keys locally. There is no account registration, phone number, or directory.

Your identity and a room use separate passphrases. Enter secrets at the masked prompts; don’t put them in command arguments or shell history.

To print your public identity fingerprint in another terminal:

vox id

Exchange the full fingerprint with your peer and verify it through a channel you already trust. A fingerprint identifies a key; it does not tell you who owns it without that comparison.

03. Make a room

In the terminal client, press : to open the command palette. Create a room and enter a room passphrase at the prompt:

:new crew

With the room open, use :invite to display its vox:// address. Share the address and room passphrase with your intended peer through a trusted channel.

On the other machine, open Vox and use :join. Enter the address and the room passphrase in the prompts. For peers behind restrictive NAT, configure an anchor before creating or joining the room.

Joining is not permission to read. A new identity can join the room and still have no readable messages. Each participant must make their own trust decision.

04. Decide who to trust

After checking your peer’s full fingerprint, trust their identity from a separate terminal. Replace the uppercase placeholder below with the actual fingerprint:

vox trust add PEER_FINGERPRINT --name alice
vox trust list

Ask your peer to verify and trust your identity as well. Trust is directional: your approval lets them read you; their approval lets you read them.

Trust applies across shared rooms. It is a node-wide decision about an identity, including rooms you share later. It also authorizes that peer to reach services you offer in those shared rooms. Make this decision deliberately.

To stop trusting an identity:

vox trust remove PEER_FINGERPRINT

Vox rotates your sender keys and re-keys the remaining trusted identities. This protects subsequent messages; it cannot take back content someone already received. Read the full consent model.

Reachability & anchors

Directly reachable peers do not need an anchor. When NAT prevents a direct connection, use an always-on host you control:

vox node --listen 0.0.0.0:0

The node prints an anchor specification in the form <fingerprint>@<multiaddr>. Pass that complete value to the clients:

vox --anchor 'ANCHOR_SPEC'

The host must be reachable at its advertised address and UDP port. For a fixed firewall rule, choose a reachable fixed listening port instead of 0. An anchor introduces peers, coordinates hole punching, and can relay encrypted traffic. It holds no room key.

An anchor is not a participant that can read the room. It is also not an anonymity service. Read the reachability design.

Reach a TCP service

Vox can offer a local TCP port through a private room. Here is the SSH example, assuming SSH already listens on port 22. Add --anchor 'ANCHOR_SPEC' to the commands that need it.

On the service host

vox serve 22

Keep it running. It prints a room address, a generated room passphrase, and a .vox hostname. Share the room details with the intended guest. Verify the guest’s fingerprint and run vox trust add GUEST_FINGERPRINT on this host.

On the guest machine

vox connect 'VOX_INVITE_ADDRESS'
vox up ROOM_ID

Replace the placeholders with the address and room ID printed by Vox; enter the passphrase at the prompt. Keep vox up running and use the SSH ProxyCommand line it prints in another terminal.

The service host must trust the guest. Room membership and the host’s trust keyring both gate access. Giving someone the invitation and passphrase alone does not authorize access to the service.

Use vox forward --help for local port forwarding when an application cannot use a SOCKS5 proxy. Read the room-bound services design.

Give your agents a shared room

Vox supports private communication between Claude Code, Codex, and OpenCode sessions. Set up the identities, shared room, and mutual trust first. Keep a Vox node running through the TUI, or run vox daemon after closing the TUI for that profile.

The daemon keeps the profile available without an interactive terminal. Follow its passphrase prompt, or use its documented --passphrase-file option with an owner-readable file for unattended use.

vox room list
vox room roster ROOM_ID
vox room post ROOM_ID "Ready to coordinate."
vox room tail ROOM_ID

Use a dedicated profile for each agent identity in this release; do not run agents as your personal identity. Configure its hooks and CLI commands to use that same profile. Each integration has setup instructions built into Vox:

vox agent plugin --help
vox agent skill --help
vox room claim --help

vox agent plugin claude, vox agent plugin codex and vox agent plugin opencode print each client’s integration and its destination. Install the matching skill with vox agent skill. Preserve existing settings when merging hooks; Codex also needs vox agent trust codex after its hook entry is installed.

The hooks deliver room messages to a session; the companion skill explains how to participate. Claim and handoff commands coordinate work between sessions. All participants must use the same Vox version for work coordination.

The room is for discussion and ownership; GitHub issues through awa hold progress and proof. For delivery behavior, claims, files and the newer explicit-node setup, see the Agent comms guide. Its --node examples are for v0.3.0, not this release.

For the integration contract and harness-specific setup, read Agent comms and Work-item interoperability.

Keep Vox current

vox update --check
vox update

If you need to restore the binary replaced by the last update, use vox update --rollback. On macOS, an update must carry the same Developer ID as the installed binary.

Review release notes before updating. This guide describes v0.2.10; future releases may change commands or behavior.