Install Marauder in 5 minutes

Prerequisites

• • A Linux, macOS, or Windows host with Docker 24+ and docker compose v2
• • git to clone the repository
• • openssl for generating the master encryption key
• • Optional: an existing torrent client (qBittorrent / Transmission / Deluge) running somewhere reachable from the host

1. Clone and copy env

Clone the GitHub repository and copy the example environment file. Everything you need lives under marauder/deploy/.

git clone https://github.com/artyomsv/marauder.git
cd marauder/deploy
cp .env.example .env

2. Generate the master key

Marauder encrypts every secret it stores (tracker credentials, client configs, JWT signing keys) with AES-256-GCM keyed by a 32-byte master key you supply via the MARAUDER_MASTER_KEY env var.

Save the key somewhere safe. Losing it means every stored credential is unrecoverable.

# Generate a 32-byte AES-256 master key (REQUIRED)
MASTER=$(openssl rand -base64 32)
sed -i "s|MARAUDER_MASTER_KEY=.*|MARAUDER_MASTER_KEY=$MASTER|" .env

# Optional: a token to gate the /metrics endpoint
METRICS=$(openssl rand -hex 32)
sed -i "s|MARAUDER_METRICS_TOKEN=.*|MARAUDER_METRICS_TOKEN=$METRICS|" .env

3. Start the stack

One command brings up four containers: PostgreSQL 18, the Go backend, the React frontend, and an nginx gateway exposed on port 6688.

docker compose --env-file .env up -d

The first start runs database migrations and bootstraps the initial admin user from MARAUDER_ADMIN_INITIAL_USERNAME and MARAUDER_ADMIN_INITIAL_PASSWORD in the env file. Both default to admin / pleasechangeme.

Change the admin password from the UI on first login, then unset both env vars and restart the backend.

4. Verify it's healthy

The stack is ready when /health returns 200 and /api/v1/system/info reports the version.

curl -fsS http://localhost:6688/health
# .

curl -sS http://localhost:6688/api/v1/system/info | jq .version
# {
#   "version": "1.0.0",
#   "commit":  "...",
#   "buildDate": "..."
# }

5. Sign in and add your first topic

Open http://localhost:6688 in a browser, sign in as admin, and use the Add topic button to paste a magnet link or tracker URL. Configure a torrent client under Clients, set it as default, and Marauder will hand future updates straight to it.

Or, from the command line:

curl -sS -X POST http://localhost:6688/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"pleasechangeme"}'

Next steps