Binary
Install the signed agent binary on Linux, macOS or Windows, and run it as a service on Linux.
Signed binaries are published on each GitHub release for:
- Linux: amd64, arm64, armv7
- macOS: Intel and Apple silicon
- Windows: amd64, arm64
Download
Download the archive for your platform, named like
agent_<version>_linux_amd64.tar.gz (.zip on Windows), and unpack it. It
contains the agent binary, an example config file and a systemd unit.
VERSION=0.1.0
curl -LO https://github.com/wilderness-cloud/agent/releases/download/v$VERSION/agent_${VERSION}_linux_amd64.tar.gz
tar xzf agent_${VERSION}_linux_amd64.tar.gzWith a Go toolchain you can also build it yourself:
go install github.com/getnabbed/agent/cmd/agent@latestVerify the download
Every archive is signed with cosign and has a SLSA build provenance attestation. See Verifying a release for the commands.
Pair and run
Pair once, then run:
./agent pair --api-url https://api.nabbed.media
./agent runpair prints a link and a code. Open the link while signed in to Nabbed,
check the code matches, and approve it. The code is valid for 15 minutes.
agent run also pairs first if needed, so for a service you can start it
straight away and read the code from its log.
Allow your library folders
The agent only imports into folders you allow. Add the parents of your libraries to the config file:
library:
allowed_roots:
- /media/movies
- /media/tvOr set NABBED_LIBRARY_ROOTS=/media/movies:/media/tv (separate with ; on
Windows). The agent looks for its config file here:
| Platform | Config file | Credentials and state |
|---|---|---|
| Linux (root or service) | /etc/nabbed-agent/agent.yaml | /var/lib/nabbed-agent |
| Linux (user) | ~/.config/nabbed-agent/agent.yaml | ~/.local/state/nabbed-agent |
| macOS | ~/Library/Application Support/Nabbed Agent/agent.yaml | ~/Library/Application Support/Nabbed Agent |
| Windows | %APPDATA%\Nabbed\Agent\agent.yaml | %LOCALAPPDATA%\Nabbed\Agent |
Start from contrib/agent.example.yaml in the archive. Unknown keys are an
error, so typos fail loudly. Run agent config to see the settings the agent
is actually using.
Run as a service on Linux
The archive includes a hardened systemd unit. It runs the agent as a dynamic system user with no privileges.
Install the binary and unit
sudo install -m 0755 agent /usr/local/bin/nabbed-agent
sudo install -m 0644 contrib/systemd/nabbed-agent.service /etc/systemd/system/
sudo install -D -m 0644 contrib/agent.example.yaml /etc/nabbed-agent/agent.yamlEdit /etc/nabbed-agent/agent.yaml: set api_url: https://api.nabbed.media
and your library.allowed_roots. The file must stay readable by the service,
so don't put passwords in it.
Grant access to your media
The service can't write anywhere outside its own state folder until you allow it. Add an override:
sudo systemctl edit nabbed-agent[Service]
ReadWritePaths=/media/movies /media/tvStart it and pair
sudo systemctl enable --now nabbed-agent
journalctl -u nabbed-agent -fThe pairing link and code appear in the log on first start.
Troubleshooting
The agent exits with code 3. It was revoked or its credentials expired. Pair it again with a new identity:
agent pair --forceThe systemd service doesn't restart after exit code 3. Remove its old identity and start it again; it pairs on start and logs a new code:
sudo systemctl stop nabbed-agent
sudo rm -rf /var/lib/private/nabbed-agent
sudo systemctl start nabbed-agent
journalctl -u nabbed-agent -fCheck its state:
agent status # identity and connection, no secrets
agent config # effective settings, secrets redacted