subnera-agent: report a Mac to your hub from the command line

subnera-agent is the command-line sibling of the subnera menu bar app. It reports a Mac to your subnera hub and, if you allow it, takes the hub's remote commands, with no menu bar and no window. This guide covers installing it, linking it, and the problems you are most likely to hit.

Who it is for

A Mac run as a server: no one sits in front of it. Train at Home is itself a GUI app, so that Mac must have a logged-in user session, which in practice means auto-login (System Settings → Users & Groups) and an Energy setup that keeps it awake (see keeping a Mac awake). If you already use the menu bar app on a Mac, you do not need the agent there; use one or the other per Mac.

Requirements: macOS 13 or later, Apple silicon.

If this Mac is already linked by subnera-agent, the subnera menu bar app shows that link read-only and does not report on its own, so the Mac is never counted twice. Run subnera-agent unlink to use the app instead.

Install

The quickest way is the one-line command from your hub. In the hub, open your pool and press + Add machine: open the CLI (server) tab, the panel shows a ready-to-paste command and a Copy command button. Paste it in Terminal on the server Mac:

curl -fsSL https://subnera.com/install.sh | SUBNERA_HUB=<hub-url> SUBNERA_TOKEN=<install-token> sh

The hub URL must be https:// (http:// is accepted only for localhost). It does three things, in this order: install the agent, link this Mac to your hub, then start it at login. Re-running it is safe: a Mac that is already linked keeps its link. If a step fails, the script says which one and prints the manual commands to finish.

The token is read from the environment, so it stays out of ps (and out of the command's arguments). It can still end up in your shell history, which is why it works once and expires after an hour: once used, the copy in your history is worthless.

Two steps instead

To install first and link yourself (the token then never goes through a pipe):

curl -fsSL https://subnera.com/install.sh | sh

The script first checks that the machine is macOS on Apple silicon. It then downloads latest.json with its signature latest.json.sig and checks the signature against the subnera release key with macOS's own openssl; if the signature is missing or does not match, it stops and installs nothing. Only then does it download the agent archive and compare its sha256 with the one in the signed latest.json; if they differ it stops and installs nothing. It installs to ~/.local/bin/subnera-agent and never uses sudo. Without SUBNERA_HUB and SUBNERA_TOKEN it links nothing: continue with the next two sections (subnera-agent link <hub-url> <install-token>, then subnera-agent install).

If ~/.local/bin is not on your PATH, the script prints the line to add:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zprofile && exec zsh -l

Manual install

If you prefer not to pipe a script into a shell, download the agent archive from the download page↗, which also shows its SHA-256, then:

shasum -a 256 subnera-agent-*-macos-arm64.tar.gz   # compare with the SHA-256 on the download page
tar -xzf subnera-agent-*-macos-arm64.tar.gz subnera-agent
mkdir -p ~/.local/bin && install -m 0755 subnera-agent ~/.local/bin/subnera-agent
xattr -d com.apple.quarantine ~/.local/bin/subnera-agent   # a browser download is quarantined

Link to your hub

If you used the one-line command, the Mac is already linked: skip to the remote control section or check it with subnera-agent status. Otherwise, in the hub press + Add machine: the panel shows the hub URL and a token starting with tok_ (see connecting a Mac). Then:

subnera-agent link https://app.subnera.com <install-token>

The token is valid for one hour and works once. link stores this Mac's key in ~/Library/Application Support/subnera/agent.json and starts with remote control off. It refuses to run if the subnera menu bar app already links this Mac, or if this Mac is already linked (run subnera-agent unlink first, which also leaves the Mac listed in the hub until you remove it there).

Start at login

The one-line command already does this. Otherwise:

subnera-agent install

This writes a per-user LaunchAgent, ~/Library/LaunchAgents/com.subnera.agent.plist, and starts it. The agent then comes back at every login and after a crash. Its log is ~/Library/Logs/subnera/agent.log. Running install again is safe. subnera-agent run does the same work in the foreground (what launchd runs), which is handy to watch it live; stop it with Ctrl-C.

Remote control

subnera-agent remote on
subnera-agent remote off

It is off by default. With it on, the hub may start, stop or restart Train at Home on this Mac, and toggle the watchdog. With it off, those commands are refused. The change applies at the next command, with no restart. See what remote control allows before turning it on.

Check it

subnera-agent status

It prints, one per line:

• the agent version;
• hub, the hub URL, and machine, this Mac's id in the hub;
• key, the last four characters of the key (never the whole key);
• remote and update check, each on or off;
• daemon: running, installed but not running, or not installed;
• last report: when the hub last received a report, or since when the agent is offline and why;
• official app: whether Train at Home is running;
• update, only when a newer version exists.

The exit code is 0 when the Mac is linked and reported within the last two minutes, and 1 otherwise, so it fits a monitoring script:

subnera-agent status >/dev/null || echo "subnera-agent is not reporting"

Update

subnera-agent update            # download, verify and install the newest release
subnera-agent update --check    # only say whether a newer version exists
subnera-agent update --auto on  # let the running agent install updates itself (off by default)

update accepts a release only if the download matches the SHA-256 in the signed release manifest, its code signature is valid and --version reports the announced version; it then replaces the binary and restarts the agent if it runs at login. Details in the updates guide.

Where things live

What	Where
Link, key and settings	~/Library/Application Support/subnera/agent.json (mode 600, in a 700 folder)
What the daemon last saw (for status)	agent-state.json, in the same folder
LaunchAgent	~/Library/LaunchAgents/com.subnera.agent.plist
Log	~/Library/Logs/subnera/agent.log
Binary	~/.local/bin/subnera-agent

Uninstall

subnera-agent uninstall            # stop the agent and remove the LaunchAgent
subnera-agent uninstall --purge    # also delete the link file and the agent's state
rm ~/.local/bin/subnera-agent      # the binary itself

Then remove the Mac in the hub, since it stays listed there after a local unlink.

Troubleshooting

Symptom	What to do
A command (run, status, link, remote, update-check) fails with exit code 78 and a message "is readable by other users. Fix it with: chmod 600 '…'"	The agent refuses to work with a key file or folder that other users can read. Under launchd it is retried at a throttled rate, so it keeps failing until you fix the permissions. Run the chmod it prints (700 for the folder). If it says the file is not owned by you, remove it and run link again.
link says "This Mac is already linked by subnera.app"	The menu bar app already reports this Mac. Unlink it there first, or keep the app and skip the agent.
status says "not linked (revoked by the hub …)"	The Mac was removed in the hub. Create a new token with + Add machine and run link again.
install fails with a launchctl error	A LaunchAgent needs a logged-in user session, like Train at Home itself. Log in (or enable auto-login), then run install again.
official app: shows unknown or not running	unknown means the agent has not reported yet: check the daemon: line. not running means Train at Home is not running for this user: open it (see the install guide).

Help

subnera-agent help lists every command, and subnera-agent <command> --help (or subnera-agent help <command>) describes one. subnera-agent --version prints the version. The agent also checks once a day whether a newer version exists, which you can turn off with subnera-agent update-check off; see the updates guide.