Install Agent HQ. Pick a way in.

1. Build hq for the phone with the features the app needs.

   hq for Android

   # hq for the phone, with the pairing and tunnel features the app uses
   # (the recipe CI runs is .github/workflows/android.yml)
   cargo build -p hq-cli --profile release-small --target aarch64-linux-android --features tunnel,bridge --locked

2. Build the APK. All four paths are required, and keep the signing key backed up: only an update signed with the same key keeps the phone's data.

   APK

   cd apps/android
   ./gradlew :app:assembleDebug \
     -Phq.bin=<hq aarch64-linux-android> -Phq.caddy=<caddy linux arm64> \
     -Phq.web=<apps/hq-web/dist/client> -Phq.keystore=<your signing key>

3. Install it over USB debugging. Always update with -r; uninstalling deletes the vault.

   Install

   adb install -r app/build/outputs/apk/debug/app-debug.apk

4. Push your model key the way the README shows (the app encrypts it under an Android Keystore key and wipes the plain copy), then switch from standby to the full daemon. Run the daemon on one machine at a time, or two of them answer the same bots.

   Full HQ

   # hq starts in standby: the web app only. For the full daemon and relays:
   adb shell "run-as example.hq.spike sh -c 'echo active > files/mode'"
   adb shell "run-as example.hq.spike sh -c 'kill \$(pidof libhq.so)'"   # the app restarts hq

Keep the phone on a charger and allow it to run in the background; the app's Keep running screen checks the settings it can. The Android README has the details, and the mobile edition lists what differs from a laptop or server.

1. Provision the box once from your machine. This installs Tailscale, Caddy, ufw and gh, creates an unprivileged hq user and writes a starter config with both chat relays disabled. <ssh-host> is an SSH alias for your server.

   Provision

   ssh <ssh-host> 'bash -s' < deploy/setup-vps.sh

2. On the server, clone the repository (same commands as above).

   Clone

   git clone https://github.com/CalvinMagezi/hq.git
   cd hq

3. Install bubblewrap, which the default sandbox mode needs, and the minisign tool, which the installer uses to check the first download.

   Dependencies

   sudo apt install -y bubblewrap minisign

4. Run the installer with the official release key from the repository, release/minisign.pub. It creates the user and directories, installs the units, writes /etc/hq/update.conf and the key, bootstraps the first binary, runs the first signature-verified update and enables the timer. It is safe to run again.

   Install

   sudo deploy/install.sh --repo CalvinMagezi/hq --channel stable --pubkey release/minisign.pub

5. Day to day.

   Updates

   hq update --check                  # exit 10 means an update is waiting
   hq update --apply --dry-run        # verify the release, change nothing
   hq update --apply
   hq update --pin <version> --apply  # exact version, downgrades allowed
   hq update --rollback               # previous binary and web files

deploy/install.sh installs HQ only. Coding agents run on a machine that has them installed, paired with hq host join; see the sessions docs. Personal agents such as Hermes and OpenClaw are optional and set up the same way; see the personal agents guide. Pick one deploy path per host: the updater owns the binary and web files, so do not also build on the server. Full walkthrough: deploy/README.md. To check a release by hand, see verifying a release.

About ten minutes

One form on Hetzner

The quickest way to a private, always-on HQ. A form creates a server in your own Hetzner Cloud project that installs signed releases, updates itself and is reachable only from your tailnet. It takes about ten minutes, most of it waiting, and costs Hetzner's hourly price for the server: about 6.50 a month for a 4 GB machine.

You need a Hetzner account with a payment method, a free Tailscale account with MagicDNS and HTTPS certificates turned on, an SSH key (ssh-keygen -t ed25519 makes one), and a model API key such as OpenRouter.

CreateInstallJoin tailnetOpen HQ

1. 1

   Make a token

   In the Hetzner Cloud console create a project, then Security, API tokens, Generate. Choose Read & Write and copy it once.

2. 2

   Fill in the form

   Open the deploy form, paste the token, and pick a name, a location, a size with at least 4 GB of memory, your SSH public key and your own IP address. Click Create server.

3. 3

   Wait 3 to 5 minutes

   After Hetzner shows the server as running. It installs HQ by itself.

4. 4

   Join your tailnet

   Run ssh root@<server-ip> hq-join, open the Tailscale login link it prints and sign in. It then prints your HQ link.

5. 5

   Open HQ

   Open that link on a device on your tailnet, paste your model key on the first screen (what it does), and send a message. Treat the link like a password.

6. 6

   Close public SSH

   Use the button on the form page once HQ opens. When you are done with the server, the same page deletes it with its firewall and key.

The server's setup data holds no secret and the admin token is generated on the server, so the form never sees it. More detail, troubleshooting and the security model: docs/HETZNER.md.

1. Join the tailnet.

   Tailscale up

   sudo tailscale up

2. Add the loopback Caddy bridge.

   Caddy

   sudo cp deploy/Caddyfile.pwa /etc/caddy/Caddyfile.pwa
   echo "import Caddyfile.pwa" | sudo tee -a /etc/caddy/Caddyfile
   sudo caddy validate --config /etc/caddy/Caddyfile && sudo systemctl reload caddy

3. Serve it on an alternate HTTPS port. Port 443 is usually taken by a public Caddyfile.

   Serve

   sudo tailscale serve --bg --https=8443 http://127.0.0.1:4749
   tailscale serve status

4. List every origin you open the UI from in /opt/hq/config.yaml, and set a web token. Without the origin you get a 403 about an unrecognised Host header. Restart HQ afterwards.

   config.yaml

   web_allowed_origins:
     - https://hq.example.ts.net:8443
   web_auth_token: "<a long random value>"

sudo tailscale serve --https=8443 off