FERROMAGNET / DOCUMENTATION

Run on Linux or a VPS

The download is a Linux x86-64 binary. The static musl build includes the web UI and SQLite. You do not need Rust, Node, Docker, or a separate database. Start with an SSH tunnel for private access.

1. Download and verify

mkdir -p ~/apps/ferromagnet
cd ~/apps/ferromagnet
curl -fSLO https://ferromagnet.app/downloads/ferromagnet-0.1.1-linux-x86_64.tar.gz
curl -fSLO https://ferromagnet.app/downloads/SHA256SUMS
sha256sum -c SHA256SUMS
# Continue only if the archive reports OK.
tar -xzf ferromagnet-0.1.1-linux-x86_64.tar.gz
cd ferromagnet-0.1.1-linux-x86_64
./ferromagnet --version

2. Choose local or persistent use

For a private local machine, run ./ferromagnet serve from the extracted directory and open http://127.0.0.1:27183. Stop with Ctrl-C. For a shared machine, enable native auth as described in the shared-host guide. For an Ubuntu/Debian VPS with systemd and sudo, use the following service setup.

# VPS only: run from the extracted directory.
sudo useradd --system --home-dir /var/lib/ferromagnet --shell /usr/sbin/nologin ferromagnet
sudo install -d -o ferromagnet -g ferromagnet -m 750 /var/lib/ferromagnet
sudo install -d -m 755 /opt/ferromagnet
sudo install -d -o root -g ferromagnet -m 750 /etc/ferromagnet
sudo install -m 755 ferromagnet /opt/ferromagnet/ferromagnet
sudo install -o root -g ferromagnet -m 640 ferromagnet.toml /etc/ferromagnet/ferromagnet.toml
sudo ./ferromagnet create-password --username YOUR_LOGIN --output /etc/ferromagnet/ferromagnet.htpasswd
sudo chown root:ferromagnet /etc/ferromagnet/ferromagnet.htpasswd
sudo chmod 640 /etc/ferromagnet/ferromagnet.htpasswd
sudoedit /etc/ferromagnet/ferromagnet.toml

Append this auth section to the VPS config:

[auth]
enabled = true
htpasswd_file = "/etc/ferromagnet/ferromagnet.htpasswd"
realm = "Ferromagnet"

Enable discovery

Edit ferromagnet.toml. Under [dht], set enabled = true after checking your provider’s rules. Choose an unused UDP port in bind; allow inbound UDP to that port through your provider firewall and any local firewall. Keep the HTTP bind on 127.0.0.1.

The supplied profile uses 10 outbound DHT queries per second, lower concurrency, two previews, and a 2 GiB preview threshold. That threshold refuses new sessions when reached; active downloads may exceed it. Use a filesystem quota for a hard limit. Monitor CPU, memory, disk, and bandwidth as your index grows.

Check indexing

Each installation starts with an empty index. Leave the crawler running and check its counters as metadata arrives. Preview playback requires available peers and compatible browser codecs. The current release supports BitTorrent v1 and plays supported media without transcoding.

For the systemd setup, edit /etc/ferromagnet/ferromagnet.toml. Its relative data paths resolve under /var/lib/ferromagnet. If using UFW, allow your SSH port before enabling the firewall; add the selected DHT UDP port. Keep port 27183 private. Also check your VPS provider firewall.

3. Start the service

sudo install -m 644 ferromagnet.service /etc/systemd/system/ferromagnet.service
sudo systemctl daemon-reload
sudo systemctl enable --now ferromagnet
sudo systemctl status ferromagnet --no-pager
sudo journalctl -u ferromagnet -n 50 --no-pager

4. Connect securely

From your computer:

ssh -N -L 127.0.0.1:27183:127.0.0.1:27183 YOUR_USER@YOUR_VPS

Open http://127.0.0.1:27183 and enter your app credentials. For access without a tunnel, put a trusted HTTPS reverse proxy in front, preserve the Authorization header, keep native auth enabled, and add edge rate limits. Basic Auth alone does not encrypt traffic. The marketing domains host only this website, not your private instance.

5. Check discovery

# From the extracted directory. Prompts for your Basic Auth password.
curl -fsS -u YOUR_LOGIN http://127.0.0.1:27183/healthz
curl -fsS -u YOUR_LOGIN http://127.0.0.1:27183/api/v1/crawler/stats
sudo -u ferromagnet sh -c 'cd /var/lib/ferromagnet && /opt/ferromagnet/ferromagnet --config /etc/ferromagnet/ferromagnet.toml stats'

Before VPS backups or upgrades, use sudo systemctl stop ferromagnet. Back up /var/lib/ferromagnet/data and /etc/ferromagnet. Restart with sudo systemctl start ferromagnet. Disable with sudo systemctl disable --now ferromagnet.

Upgrade, backup, and remove

Stop the process cleanly before upgrading. Back up the entire data directory while stopped, along with the config and private password file. Never copy only the main SQLite file while the app is running; use SQLite’s online backup API for a live backup.

Keep the previous binary and matching database backup. Test the new binary with --version, then replace only the binary and release documents; retain your config and data. If rolling back after a database change, restore the matching stopped backup too. To remove, stop the service and delete its binary and data only when you no longer need the index.

Troubleshooting

Empty index: confirm DHT is enabled, the chosen UDP port is free and allowed, outbound peer connections work, and crawler counters increase.
Address already in use: change the HTTP or DHT port and update your tunnel or firewall accordingly.
401 response: authenticate with the username you created. The ingestion token does not grant UI access.
429 / previews refused: let idle sessions expire, check disk usage, and review limits.
Playback fails: try another compatible file with available peers or use an external player. Treat expiring external stream links as secrets.
Binary will not run: verify uname -m is x86_64, check archive checksum and executable permissions. The current binary requires Linux x86-64.

After a few days, send feedback with your version and hosting type. Redact credentials, hostnames, private URLs, and torrent details from logs.

← Back to Ferromagnet