On this page
An agent can spend your time away from the desk waiting for a single confirmation. Checking progress, answering questions, and approving the next step are often manageable from a phone.
This setup keeps agents and development environments on NixOS: Herdr manages terminal sessions, Collie provides the mobile web interface, and Tailscale connects the devices. Install the system components once, sign in and pair the phone, then open the app whenever needed.
Why keep agents on the development machine
A consistent egress. Agent requests originate on the development machine, regardless of the phone switching between Wi-Fi and cellular. A shared route or proxy can consolidate egress and reduce account network changes. Dynamic IPs and routing can still affect the exit address. Tailscale here handles web access; stable egress does not guarantee lower suspension risk.
One interface for multiple agents. Claude Code, Codex, and other CLIs keep their own accounts and configuration. Terminal access is general; status detection, conversation history, and approval views depend on the integration.
One environment to maintain. Repositories, credentials, and project flake.nix files stay on the host. Use the phone for brief interventions and the desktop for complex diffs and extensive edits.
What each component handles
- Herdr organizes terminals into workspaces, tabs, and panes. Tasks continue after its client detaches.
- Collie provides the mobile interface, shortcut keys, and supported agents’ session views. It supports a home-screen app and push notifications.
- Tailscale Serve supplies private HTTPS access within a tailnet, without opening Collie’s port to the public internet.
Phone browser / home-screen app
│ Tailscale + HTTPS
▼
Collie
│ Herdr socket
▼
Herdr
├─ Claude Code
└─ Codex / other terminal programsEach Unix user has their own sessions, Collie instance, and Tailscale identity. Agent requests to model services still follow the host’s existing outbound route.
First use: four steps
On an already configured host, start here: no .env or service files to write. For a new NixOS installation, complete the system configuration below first.
Install Tailscale on the phone and use the same account on the host. Enable MagicDNS and HTTPS Certificates, approve nodes, and allow phone access to the node’s TCP 443. Agent CLIs should already be installed and authenticated.
1. Start agents inside Herdr
SSH directly into your normal account, rather than switching with sudo -iu:
ssh alice@devbox
herdrInside Herdr, enter the project, load its environment (such as nix develop), and start claude or codex. Add tabs or panes for parallel tasks.
Press Ctrl+B, release it, then press Q to return to the outer shell. Tasks keep running. Herdr does not adopt agents already running in other terminals.
2. Sign into your Tailscale instance
systemctl --user start collie-tailscaled
collie-tailscale up --hostname=devbox-aliceChoose your own node name and open the printed authorization link. Existing authenticated instances need no repeat authorization. Use collie-tailscale to address the current user’s daemon.
3. Start Collie
collie start
collie doctorThe printed tailnet HTTPS address is the phone’s entry point; collie url retrieves it later. Do not open 127.0.0.1 on the phone. For an existing installation, an upgrade, or changed configuration, use collie restart instead of start.
A pairing warning from doctor is expected before the first phone is paired. Complete the next step.
4. Pair the phone
collie pairKeep Tailscale connected on the phone, scan the QR code or open the pairing link, and name the device. Pairing codes are single-use and last ten minutes; device credentials remain valid until revoked by default.
On iPhone, use Safari’s Add to Home Screen; on Android, choose Install app or Add to Home Screen. Reopen from the icon and confirm that agents are visible and accept input. If the app did not inherit browser pairing state, generate a fresh code and pair within the home-screen app.
A paired phone has the Unix user’s terminal permissions. Pair only your own devices. Permissions
After setup, just open the app
Keep Tailscale connected and open the home-screen app. There is no need to SSH in, authorize, or pair each time. Run herdr on the desktop to return to the same terminals.
Access after SSH logout requires linger, which the generic module below enables. On existing deployments, check with loginctl show-user "$USER" -p Linger; an administrator can enable it if needed. Rebooting still ends agent processes, which must be started again inside Herdr.
Optional: notifications when an agent needs input
collie push-keys
collie restart
# After granting permission and subscribing on the phone:
collie push-testiPhone Web Push requires iOS 16.4 or later and a home-screen app. Keep push keys in user storage, outside the system flake.
NixOS: configure the host once
Use the public module from my-nix-pkgs with an existing system flake. It supplies per-user Tailscale, Collie defaults, and systemd dependencies, leaving users with the four steps above.
The example pins commit d9f545d: Collie 1.23.0, Herdr 0.9.5, and Tailscale 1.104.1. Commands use Bash. The configuration directory is ~/nixos, with hardware settings and normal user alice already defined in configuration.nix.
Import the module
Nix needs nix-command and flakes enabled. If necessary, first add nix.settings.experimental-features = [ "nix-command" "flakes" ]; to your current configuration and rebuild using your existing process.
cd ~/nixos
COLLIE_PKGS_REV=d9f545d9ff3ce18c50a7749310f3219f51da53ea
curl --fail --location \
"https://raw.githubusercontent.com/LMMMMMJ/my-nix-pkgs/${COLLIE_PKGS_REV}/docs/examples/collie-mobile.nix" \
--output collie-mobile.nixReview the downloaded module, then merge the input and settings below into the flake, preserving existing system modules. Compare any existing file before replacing it.
Complete flake configuration
{
inputs = {
nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
my-nix-pkgs.url =
"github:LMMMMMJ/my-nix-pkgs/d9f545d9ff3ce18c50a7749310f3219f51da53ea";
};
outputs = { nixpkgs, my-nix-pkgs, ... }: {
nixosConfigurations.devbox = nixpkgs.lib.nixosSystem {
system = "x86_64-linux";
modules = [
./configuration.nix
./collie-mobile.nix
({ pkgs, ... }: {
environment.systemPackages = [ pkgs.python3 ];
services.collieMobile = {
enable = true;
colliePackage =
my-nix-pkgs.packages.${pkgs.stdenv.hostPlatform.system}.collie;
herdrPackage =
my-nix-pkgs.packages.${pkgs.stdenv.hostPlatform.system}.herdr;
tailscalePackage =
my-nix-pkgs.packages.${pkgs.stdenv.hostPlatform.system}.tailscale;
users.alice = {
port = 8787;
tailnetLogin = "alice@example.com";
};
};
})
];
};
};
}Replace devbox, alice, and the Tailscale login identity. On ARM, set system to aarch64-linux. pkgs.python3 supplies the runtime for Herdr’s agent hooks; installing it system-wide makes it available to agent terminals and background services. Assign different local ports to additional users.
Rebuild the system
git add flake.nix collie-mobile.nix
nix flake lock
sudo nixos-rebuild build --flake .#devbox
sudo nixos-rebuild switch --flake .#devboxSave flake.lock. Remove duplicate collie installation entries so the command resolves to the module’s wrapper, preserving existing state. Users can now SSH in and follow the four steps above.
How this differs from an existing my-nix-machine deployment
The HomeServer configuration in my-nix-machine already provides per-user ports and defaults; do not install this generic module again. It leaves the Tailscale email unset by default, allowing users to select their account in the browser. Its collie-tailscaled service starts on demand, so static is expected. Administrators enable linger when needed:
sudo loginctl enable-linger aliceThe generic module used here instead requires tailnetLogin and enables the daemon and linger automatically. The user steps are the same, but expected service enablement differs.
Troubleshooting and upgrades
Open the target session on the phone, run pwd in a test shell, then close all SSH sessions and confirm input still works. Start troubleshooting with collie doctor; routine use needs no systemd or socket checklist.
Common issues and agent integrations
- Page unavailable: check phone Tailscale, node approval, MagicDNS, HTTPS, and TCP 443 policy. Initial certificate issuance can take a moment.
- Pairing or access refused: generate a fresh code; if a trusted identity is configured, verify the Tailscale login name.
- Agent missing: confirm it runs inside the same user’s Herdr.
- Agent status incorrect: check integrations and
python3, installing only what you use:
herdr integration status
command -v python3
herdr integration install claude
# For Codex: herdr integration install codexInstallation changes agent user configuration. Restart the agent inside Herdr and complete its trust confirmation. Ordinary terminal viewing and keystrokes do not require every integration. Integration documentation
For further diagnosis, inspect logs:
journalctl --user -u collie -u collie-tailscaled -n 80 --no-pagerAdministrators upgrade software through Nix. With this configuration, first change the pinned revision in my-nix-pkgs.url and review matching module changes, then run:
nix flake update my-nix-pkgs
sudo nixos-rebuild build --flake .#devbox
sudo nixos-rebuild switch --flake .#devboxEach user then runs collie restart and collie doctor. Restarting refreshes the service’s Nix store paths without requiring new pairing. When replacing a phone, find its name with collie devices list and revoke it with collie devices revoke old-phone.