FERROMAGNET / EARLY ACCESS

Run on Whatbox

Pilot-tested on one Whatbox account with version 0.1.1: password setup, authenticated SSH-tunnel access, fresh-index discovery, a Sintel video preview, and idle cleanup. This is still an early beta, and other slots may differ. Check provider policies before running a DHT crawler. Ferromagnet is independent of Whatbox.

You need SSH access, Linux x86-64 (uname -m), curl, tar, sha256sum, tmux. No root or Docker is needed. If a tool is unavailable, ask Whatbox support rather than installing system packages.

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 deliberately

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; these settings are a starting point, not a resource guarantee.

Your first few days

Every install starts with an empty database. Leave it running, check crawler activity, and allow time for metadata to accumulate. No exact completion time or network coverage is guaranteed. Preview availability depends on peers and browser codecs. No transcoding or v2-only torrent support.

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. Leave the conservative profile in place during the pilot.

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. Confirm provider-supported startup options after the pilot. 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. ARM and macOS binaries are not in this beta.

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