All docs
Setup

Getting started

Install the host agent and connect from your client in under five minutes.

Last updated July 5, 2026

Getting started

This guide walks you through installing the host agent on the machine you want to control, pairing your client device, and establishing a session.

Prerequisites

  • Linux (X11 or Wayland/PipeWire), macOS 12+, or Windows 10+
  • A second device to act as the client (any of the above)
  • Both devices on the same network, or a reachable path between them
  • The TUF root key from qubox.app/.well-known/tuf/ (or your own TUF mirror — see self-hosting)

Install the host agent

Pick your platform:

Linux (deb)

curl -fsSL https://qubox.app/install.sh | sh
sudo qubox install
sudo systemctl enable --now qubox

Linux (rpm)

curl -fsSL https://qubox.app/install.sh | sh
sudo qubox install
sudo systemctl enable --now qubox

Linux (AppImage, no root)

curl -fsSL https://qubox.app/install.sh | sh
qubox user-install
systemd --user enable --now qubox

macOS

brew install qubox/tap/qubox
sudo qubox install
sudo launchctl load -w /Library/LaunchDaemons/com.qubox.daemon.plist

Windows (MSI)

Download qubox-vX.Y.Z-x86_64.msi from the latest release, run it, and the daemon service starts automatically.

Pair your client

On the machine you want to control from:

qubox-client-cli pair

The CLI prints a 6-word pairing phrase. Either:

  • Read the phrase aloud and type it on the host, or
  • Scan the QR code shown on the host with the client, or
  • Copy the host's mDNS hostname (<hostname>.local) and skip the phrase

Pairing tokens are stored at ~/.config/qubox/pairings.json on each device. The host never sees your client's token; the client never sees the host's private key.

Connect

qubox-client-cli connect studio-pc

The CLI negotiates a QUIC session (with 0-RTT on repeat connections), discovers the best available path, and starts streaming. Latency is typically 5-20 ms on a local network.

Verify

Run qubox-client-cli status to see active streams, packet loss, and RTT. Use qubox-client-cli doctor if anything looks wrong — it runs through the most common connectivity issues and prints a fix-it checklist.

Next steps