Remote Pi
TutorialsDocsGitHub Install
Tutorial · 4 of 4

Daemon mode

So far your agents only run while a terminal is open. Daemon mode keeps a folder running as a background agent that survives logout, restarts on crash, and answers your phone at 3am. This is the how; for the why — and how it compares to all-in-one platforms — see Why Pi.

The shape of it

One supervisor runs per machine. Under it sit N background agents — one per folder you promote. The supervisor is a normal user service: launchd on macOS, systemd --user on Linux. It starts at login, survives reboots, and respawns any agent that crashes.

Lock down tool permissions first
A daemon inherits the same Pi tool permissions your interactive session has — Bash, Edit, Write all run without a prompt, because no one is at the keyboard to approve them. Configure Pi's tool permissions to taste before you promote a folder to a 24/7 daemon. A tool-approval gate is on the roadmap.

1. Install the supervisor (once per machine)

From inside Pi:

In Pi — text
/remote-pi install

That single command does two things:

  • Installs and activates the user-level supervisor service (launchd / systemd --user), so it auto-starts at login and after reboot.
  • Symlinks the remote-pi and pi-supervisord CLIs into ~/.local/bin/so you can manage daemons from any shell. If that directory isn't on your $PATH, the command prints the line to add.

This is a separate, explicit opt-in — it is not part of the regular setup wizard. You only run it on machines where you want 24/7 agents.

2. Promote a folder to a daemon

First make sure the folder is configured the normal way — run /remote-pi in it once (the wizard), and pair your phone if you want to reach it remotely. Then register it:

Shell — bash
remote-pi create ~/Movies --name "Video Editor"
# → Daemon registered: id=4e39152d name="Video Editor" cwd=/Users/you/Movies · started

The id is a stable hash of the folder path (sha256(realpath)[:8]), so it survives moves and is the same on every machine. With the supervisor running, create starts the daemon right away — there is no separate start step. It restarts on crash and comes back after a reboot on its own.

One daemon per folder
The by-path id rejects a second daemon in the same directory at create time. Pairing stays interactive — a daemon reuses the keypair and paired devices from the earlier /remote-pisession in that folder; it doesn't show a QR itself.

3. Manage the fleet

Every command works as a Pi slash command (/remote-pi …) and, once the CLI is linked, as a plain shell command (remote-pi …):

Fleet commands — bash
remote-pi daemons                  # list registered daemons + state
remote-pi daemon status            # pid, uptime, restart count
remote-pi daemon send 4e39152d "Cut the first 30s of the latest clip"
remote-pi daemon restart           # restart all
remote-pi daemon stop              # stop all

A daemon receives a prompt as if a user typed it; its response flows back through the same mesh and relay you configured — your phone sees it live, and other agents on the machine see it over the local mesh.

Where the logs are

Logs — bash
# Linux
journalctl --user -u remote-pi-supervisord -f

# macOS
tail -f ~/.pi/remote/supervisord.log

Each daemon's output is forwarded into the supervisor log with a [<cwd>] prefix, so one stream shows the whole fleet.

Removing a daemon

Cleanup — bash
remote-pi remove <id>              # unregister one daemon (folder config kept)
remote-pi uninstall                # remove the supervisor service (registry kept)

uninstall is reversible — re-running /remote-pi install later brings every registered daemon back. Full flags and paths are in the reference docs.