Collie on Omarchy

Collie on Omarchy

Collie is a self-hosted phone web UI for the AI agents running in your terminal — start coding agents on your Omarchy machine, then watch, approve, and answer them from your phone over Tailscale.

TL;DR

omarchy pkg add collie-bin

It takes ~2 minutes (v1.22.4-1, ~40.8 MB). Then run collie start, scan the printed QR with your phone, and pair the device — no port forwarding, no domain, everything stays on your Tailscale tailnet.

Free forever (MIT). This is the exact use case it was built for: you're at the coffee shop, your agent on your home machine blocks on an AskUserQuestion, your phone buzzes.

The honest caveat up front: Collie is young and fast-moving (repo created June 2026, releases roughly daily — upstream published v1.22.6 on 2026-10-18, while the store package is at 1.22.4-1). And a paired device equals full shell access — "Treat the URL as a root login," per the docs. This is a security-sensitive tool; the guide covers the trust model because the repo's own docs insist on it.

Getting started (5 minutes)

1. Install.

omarchy pkg add collie-bin. Prerequisites from the install docs: Tailscale up on the host (tailscale up), HTTPS enabled for the tailnet (admin console → Enable HTTPS — collie start errors out if it's off), and the Tailscale app on your phone signed into the same account. (Confirm the prereq flow on-machine — this is from upstream docs, not a live test.)

2. First start.

Run collie start. The bridge builds if needed, starts, and prints the URL plus a QR code (collie qr reprints it). First run detects your terminal multiplexer and prompts for a choice — Herdr is the primary supported backend in 1.0; tmux, zellij, tuios, and Tern are experimental ("testing is limited to a single operator on one machine — bug reports welcome"). Set COLLIE_MUX=herdr in your .env to skip the prompt. On Linux, collie start runs the bridge as a systemd --user service (stops on logout; loginctl enable-linger $USER for servers).

3. Pair your phone.

Collie runs tailscale serve for you, terminating TLS on your MagicDNS name — the bridge binds loopback only, never 0.0.0.0. Set COLLIE_TRUSTED_USER=you@example.com in your .env and Collie rejects anyone else on the tailnet. Then collie pair on the host: an 8-char code, good for 10 minutes (or collie pair --expires 30d). Enter it in the phone PWA under Settings → Paired devices. Since 1.18.0, every API request — reads included — needs a paired device token; before that, anyone who could reach the URL could read every pane. Lost your phone? collie devices revoke <label> works immediately, no restart.

4. The three things everyone needs to know:

• The dashboard sorts by "needs your input." Panes running Claude Code, Codex, OpenCode, pi, omp, Grok, Antigravity, or Muse get per-harness "input profiles" — Collie reads the terminal screen and up-levels things like Claude's AskUserQuestion into tappable buttons, instead of making you squint at raw terminal text. Push notifications (Web Push/VAPID — run collie push-keys to generate keys) fire when an agent blocks on input.
• It's not just a terminal mirror. There's a configurable keys pad (Esc/Ctrl+C/arrows, custom chords), quick replies and slash commands from quick-replies.toml/commands.toml, a Files screen with read-only git diffs and file attachments, device pairing management, "crews" (several machines behind one URL with failover), and collie stt setup for voice input via the Whistle speech engine. No telemetry — only an update check to GitHub.
• Never use tailscale funnel. This is explicit in the security docs: funnel exposes the UI to the public internet, and since a paired device is full shell access, the URL must stay on your private tailnet. Also note: all incoming keystrokes are recorded to ~/.local/state/collie/audit.log.

5. Where its config lives.

Binary: ~/.local/share/collie/current/bin/collie (symlinked to ~/.local/bin/collie via collie link; updates keep one previous version in ~/.local/share/collie/versions/). Config: ~/.config/collie/.env, plus ~/.collie/config.toml (machine layer) and <config-dir>/config.toml (instance layer; env wins over both — collie config init writes a commented template). Live-reload customizations (no restart): commands.toml, keys.toml, quick-replies.toml, theme.toml, launchers.toml. State: ~/.local/state/collie/ (audit log, update.json, local-secret, surface samples, paired devices). Logs: journalctl --user -u collie.

6. CLI pro tip.

collie --skill prints an agent-facing brief from the binary (no network); collie docs --all prints all docs; collie doctor --json runs rich health checks. And because the phone never touches the multiplexer directly — everything flows through the Bun bridge (/api/snapshot polling, POST to /api/pane/:id/reply) — you can inspect what's happening with plain curl.

Common issues & fixes

Sourced from the real GitHub issues on AltanS/collie (both open as of 2026-10-18) and the documented constraints in the repo — nothing invented.

Phone shows "device not paired" or 403 errors everywhere

Pairing is mandatory since 1.18.0 — every request needs a device token.

Fix: Run collie pair on the host and enter the 8-char code in Settings → Paired devices. If pairing broke after a config change, collie devices list and devices revoke <label> to reset. Lost phone: revoke is immediate, no restart needed.

Every send from the phone is refused — "Collie cannot read this screen"

The screen-reader profile doesn't recognize the agent's current screen. Open issue #505 (Oct 2026): OMP 18.11's default powerline status line sits where Collie's omp reader profile expects the input box's top edge, so findInputFrame finds no frame. Also noted: a pi pane with an extension footer refused every send (fixed in 1.22.5/1.22.6), and a Claude picker or "Heads up" notice can block taps.

Fix: Workaround: use the "Type here" (keys) path instead of the reply path. For debugging, collie doctor will point you at the frame samples in ~/.local/state/collie/surface/inbox.jsonl that you can send to the project's lab.

The phone offers an update, but it fails with a vague "staging stopped" error

Known race (open issue #503): the update is offered while the GitHub release is still a draft, the manifest 404s, and the phone shows only "staging stopped before the new version was laid down."

Fix: Nothing was changed — wait a minute and retry, or collie update --rollback if you need to go back. Note: on Omarchy package installs, collie update refuses entirely — "package-manager installs are updated by the package manager" — so you update via the Omarchy package.

Pane text shows up in phone app-switcher screenshots

Known platform caveat, not a bug: Android screenshots the app before the page hears backgrounding; iOS gives no guarantee.

Fix: Treat anything typed in visible panes as potentially visible in recent-apps thumbnails. There is no mitigation — don't run secrets in panes Collie watches.

"collie-bin is not on the AUR" per upstream docs, but it's in the Omarchy store

The upstream install docs (as of Oct 2026) say to build from packaging/aur in the repo clone (git clone ... && cd collie/packaging/aur && makepkg -si), and that sudo pacman -S collie-bin (Omarchy) will replace the clone "once published."

Fix: If the store package exists and works, those docs are simply stale — but flag any install-path discrepancy when verifying, since the store package may be newer than upstream's docs.

Pairs well with / If you hate this, try

Pairs well with

• Herdr (the primary multiplexer backend — the Collie + Herdr pairing is the project's 1.0 target). Tailscale — which Collie already assumes. Any of the supported agents: Claude Code, Codex, OpenCode, pi, omp, Grok, Antigravity, Muse.

If you hate this, try

• vibetunnel for a simpler "watch my Claude Code from anywhere" terminal mirror — no pairing, no push-on-blocked-input, but much less to configure. Or DIY: tmux + Tailscale + Mosh/Termius — full raw terminal on your phone over the tailnet, free and universal, but "proper painful" on a phone keyboard with no glanceable dashboard.

Comparison: Collie vs similar apps

Verdict: Use Collie if you run coding agents in tmux/Herdr panes and want glanceable phone control with approval buttons and push alerts; use vibetunnel if you just want to watch from a browser; use DIY SSH if you trust your thumbs.