Docker

The agent image is ghcr.io/wilderness-cloud/agent, built for linux/amd64, linux/arm64 and linux/arm/v7. It has no shell and runs as user 65532.

Before you startCopy Anchor Link

• A Nabbed account. See Create an account.
• Docker 20.10 or newer, or Docker Compose.
• The folders your movies and TV shows live in, or should live in.

Run the agentCopy Anchor Link

name: nabbed

services:
  agent:
    image: ghcr.io/wilderness-cloud/agent:0.1
    restart: unless-stopped
    environment:
      NABBED_API_URL: https://api.nabbed.media
      NABBED_LIBRARY_ROOTS: /media
    volumes:
      - data:/data # credentials and state: must persist
      - ./downloads:/downloads # downloads before they're imported
      - /srv/media:/media # your libraries
    ports:
      - "6881:6881/tcp" # BitTorrent, optional but faster
      - "6881:6881/udp"
    read_only: true
    tmpfs:
      - /tmp:size=64m,mode=1777
    cap_drop: [ALL]
    security_opt:
      - no-new-privileges:true
    stop_grace_period: 30s

volumes:
  data:

docker compose up -d
docker compose logs -f agent

The 0.1 tag picks up fixes automatically. Before 1.0 a new minor version may include breaking changes, so moving to it is up to you.

Pair it with your accountCopy Anchor Link

On first start the agent prints a link and a code:

To pair this agent, open: https://app.nabbed.media/device?code=ABCD-EFGH
and enter the code: ABCD-EFGH

Open the link while signed in to Nabbed, check the code matches, and approve it. The agent connects within a few seconds and appears under Settings → Agents.

A code is valid for 15 minutes. If it expires, restart the container to get a new one.

Give it access to your libraryCopy Anchor Link

The agent only writes inside folders listed in NABBED_LIBRARY_ROOTS. Mount the parent of your libraries into the container, then allow the path as the container sees it:

volumes:
  - /srv/media:/media
environment:
  NABBED_LIBRARY_ROOTS: /media

To allow several separate folders, separate them with :, for example /movies:/tv.

When you add a library folder in the web app, use the path inside the container, such as /media/movies.

Fix permission errorsCopy Anchor Link

The container runs as user 65532, so bind-mounted folders must be writable by it. Either hand them over:

sudo chown -R 65532:65532 downloads /srv/media

or run the container as your own user, which is often simpler when a media server reads the same files. Add user: "1000:1000" to the Compose service (use the output of id -u and id -g), or --user "$(id -u):$(id -g)" to docker run.

UpdateCopy Anchor Link

docker compose pull && docker compose up -d

The agent keeps its identity in the data volume, so it reconnects without pairing again.

TroubleshootingCopy Anchor Link

The agent keeps exiting with code 3. It was revoked in the web app, or its credentials expired. Pair it again with a new identity:

docker compose run --rm agent pair --force

Imports fail with a "not allowed" notice. The library folder in the web app isn't inside NABBED_LIBRARY_ROOTS, or uses the host path instead of the path inside the container.

Check the agent's state:

docker compose exec agent agent status   # identity and connection
docker compose exec agent agent config   # effective settings, secrets redacted