Your machines

The local agent

Every machine you sign in from registers itself. cloudmorrow login enrols it, writes its config and starts it under your own account — a launchd agent on macOS, a systemd user unit on Linux. There is no token to copy and nothing to run by hand. On Linux the account is set to linger, so the unit keeps running when you log out and starts at boot; and systemctl --user is reached over the session bus even from a shell that came in over ssh, which would otherwise say only "Failed to connect to bus". If a machine has no session for you at all, that message now says to loginctl enable-linger.

It runs as you, not as a service account, so it works on your files with your permissions and needs root nowhere. It belongs to the Cloudmorrow user who signed in: your agents are yours, and nobody else can see or drive them.

Signing in again from the same machine rotates its credential rather than making a second agent. cloudmorrow logout stops it and forgets the credential.

To see your machines and what they have done:

cloudmorrow agent list
cloudmorrow agent run 1 backup --payload '{"paths":["/srv/data"],"name":"srv"}'
cloudmorrow agent jobs 1

The agent runs the code that was installed when it started, so an upgrade needs a restart to take effect — cloudmorrow update does that for you.

What a job can be:

type	what it does
ping	liveness, and which agent version answered
sysinfo	hostname, platform, CPUs, load, disk usage
backup	tar.gz some paths into the agent's backup dir, with retention
shell	run a command — off unless that machine enables it

Besides jobs, each tick the agent runs the local backups the person set up for that machine in Files (above): the folders are read below backup_roots like a backup job's, and the copies go into the person's My Files through the agent's own calls (/api/agent/syncs), never the record API.

Everything a machine may do is declared in its own ~/.config/cloudmorrow/agent.toml rather than decided by the server: backups only read below backup_roots (your home, by default), and shell needs allow_shell = true there. A job asking for anything else comes back failed, with the reason.

For a headless box you never sign in on — a NAS, say — mint a token with cloudmorrow agent enroll-token and use the install command it prints.

The server's own agent

The server is the one machine nobody signs in on, so it enrols itself — straight against its own database, no token to carry — and runs as the service account rather than as anybody:

sudo cloudmorrow-server agent-install --run-as cloudmorrow

install-server.sh does this for you, right after it has made the first account for it to hang on; if it could not make one, it says so and prints the command for after you have. It writes /etc/cloudmorrow/agent.toml and a system unit at /etc/systemd/system/cloudmorrow-agent.service — the one place Cloudmorrow installs anything outside a user's own home. Run it again to rotate the token; nothing is duplicated.

Its backup roots are the server's own data_dir and notes_dir, so cloudmorrow agent run <id> backup on it backs up the thing worth backing up.

The server's venv installs cloudmorrow[server,agent,tui] for this — it runs an agent, so it needs what an agent needs, and it has the terminal app, so it needs what that needs. A deployment from before that was true has only [server], and one cloudmorrow update server --force reinstalls it with all three.

The agent talks to the API like any other client, so it has to be able to reach it. On a server that answers only its reverse proxy (allowed_client_ips), that means adding the machine's own address to the list and pointing the agent at the local port with --url.

Notifications

What happens to you elsewhere — a Quill shared with you, somebody asking an administrator for one, an approval asked, a machine's sync — leaves a note on the server. The bell carries the count of the unread ones, and is there whether anything is unread or not, so the last fifty are always one tap away:

• The web app: in the top right corner of every tab's screen, beside Me. A tap opens the list, newest first, and opening it reads them.
• The terminal app: at the far right of the top bar; ringing it (f8, or a click) opens the list, with one button to say you have read them.

Each note is also pushed to every device that has notifications on, so a computer's browser pops it as a banner the way a phone does, and a click on the banner opens the list. To turn them on in Chrome (or any browser on a computer), open the bell, or Me, and press Turn on; the browser asks once. Chrome shows them while it is running, even with the tab closed.

curl -s $CLOUDMORROW/api/notifications -H "Authorization: Bearer $TOKEN"