FERROMAGNET / DOCUMENTATION

Run on Whatbox

Install Ferromagnet on your Whatbox slot and access it from your browser over SSH. The app runs in your home directory and includes its own password setup. Check your provider’s rules before enabling DHT discovery.

You need SSH access, Linux x86-64 (uname -m), curl, tar, sha256sum, tmux. No root or Docker is needed. If a required tool is missing from your slot, contact Whatbox support.

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. Protect your private instance

Other users on a shared host may be able to reach loopback ports. Enable native authentication even when using an SSH tunnel. Choose your own login name; this command prompts for a password.

umask 077
./ferromagnet create-password --username YOUR_LOGIN
chmod 600 ferromagnet.htpasswd

Add the following to ferromagnet.toml. The password file path is relative to the directory where you run the app. The built-in command prompts twice without echoing your password and creates a private file. It refuses to replace an existing file. To change credentials, generate a new file with --output new.htpasswd, replace the old file, and restart the app.

[auth]
enabled = true
htpasswd_file = "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.

3. Keep it running

Run these from the extracted release directory. If port 27183 is occupied, choose another HTTP port in the config and in the tunnel below. Start with the supplied resource limits and adjust them to suit your slot.

tmux new-session -s ferromagnet
./ferromagnet --config ferromagnet.toml serve
# Detach with Ctrl-B, then D. Reattach later:
# tmux attach -t ferromagnet

tmux survives an SSH disconnect, not a host reboot. For startup after a reboot, use your provider’s supported startup options. Inside tmux, Ctrl-C stops the app cleanly.

4. Open from your computer

Run this on your own computer, replacing the SSH login and host with your Whatbox details. Keep the tunnel open, then visit http://127.0.0.1:27183 and sign in.

ssh -N -L 127.0.0.1:27183:127.0.0.1:27183 YOUR_USER@YOUR_SERVER.whatbox.ca

External players must run on a device that can reach this tunnel. No public preview server is needed.

5. Check progress

# 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
./ferromagnet stats

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.

Provider references

Whatbox software guidelines · SSH access. Guidelines checked October 28, 2026. Shared-host software must not burden other users.

← Back to Ferromagnet