# spill > spill is a modern torrent client built in Rust. Run it as a single-user daemon on Linux and macOS, or embed its engine in your application. Humans and AI agents can use either path. ## Choose a path - Operate the daemon: install below, start a persistent process, and control it through CLI JSON output. - Integrate into an application: use the Rust library, not a daemon subprocess, when you need in-process torrent functionality. See Rust integration below. - [User guide](https://spill.rs/docs/): follows the latest published release, not development main. Check `spill --version` and use matching API documentation. Source examples describe their own checkout; do not assume an unpublished API exists in the installed crate. ## Install the daemon ```sh curl -fsSL https://spill.rs/install.sh | sh spill --version ``` [Inspect the installer](https://spill.rs/install.sh) first if required by your execution policy. It installs the latest published release to `~/.local/bin`, verifies SHA-256 checksums, and does not use sudo, edit PATH, or start services. Follow its PATH instructions or invoke `"$HOME/.local/bin/spill"` directly. Prebuilt platforms: Linux x64/ARM64 with glibc 2.39+ and Apple Silicon macOS 11+. Requires curl, tar, and sha256sum or shasum. Cargo installation is also supported: ```sh cargo install spill --locked ``` Cargo requires stable Rust and a C compiler. Older glibc systems, Alpine/musl, and Intel Macs should use Cargo or build from source. Windows is unsupported. spill is not yet in OS package managers. See [installation, manual downloads, services, and upgrades](https://spill.rs/docs/install/). Stop the daemon before replacing its binary; before 1.0, catalog upgrades can require a fresh state directory. Keep downloaded payload. ## Operate and automate ```sh spill health spill serve ``` Check health before starting another daemon. `serve` runs in the foreground indefinitely; manage it as a persistent process, not a command expected to finish. Use another terminal or process for client commands: ```sh spill add /absolute/path/to/file.torrent spill --json list spill --json get ID spill files ID spill pause ID spill resume ID spill set ID upload_limit=1048576 seed_ratio=2 spill remove ID spill shutdown ``` Replace the torrent path and `ID` with real values. `add` prints the torrent ID; unambiguous prefixes work. It also accepts quoted magnets and HTTP(S) torrent URLs. Downloads default to `~/Downloads`; `--output /absolute/directory` overrides that per torrent. Rates are payload bytes/second; zero means unlimited. Prefer `--json` for automation: response data is one JSON document per line. Avoid `list --watch` in noninteractive work because it waits until interrupted. `remove` keeps files; only add `--delete-payload` when deletion is intended. `shutdown` stops the daemon cleanly. Exit codes: 0 success, 1 operation failed, 2 invalid input, 3 no matching torrent, 4 daemon unreachable, 130 interrupted watch. For 4, check the process, control socket, and permissions. Use `spill --socket /absolute/path --json COMMAND` for custom sockets. See [CLI and control protocol](https://spill.rs/docs/cli/). Configuration is read only with `spill serve --config /absolute/path/to/spill.toml`. Unknown keys are errors; paths must be absolute and TOML does not expand `~` or environment variables. See [configuration](https://spill.rs/docs/configuration/). ## Rust integration ```sh cargo add spill --no-default-features cargo add tokio --features fs,macros,rt,net,time ``` Use documentation and examples matching your dependency version. - Start with `docs/library.md` in the matching source checkout and the published [user guide](https://spill.rs/docs/). - Consult [docs.rs](https://docs.rs/spill) at the exact dependency version for API signatures. Do not infer Rust APIs from CLI commands. - Run the `download` and `progress` examples from the matching [source](https://github.com/spillrs/spill). The latter demonstrates concurrent transfers and persisted recovery. - Supply a Tokio runtime with I/O and time drivers. No daemon, SQLite catalog, signal handler, or global tracing subscriber is required. - `spill::engine::download` is a one-shot helper with public DHT enabled, no LAN permission or port mapping, and no stored recovery record. - Use `Session` and `TorrentHandle` for concurrent torrents, networking policy, progress, persistence, and cancellation with joined cleanup. Reusable sessions require explicit DHT consent. - Retain handles, request stop, and await cleanup before reusing destinations. Dropping a future cannot join cleanup. Partial-file recovery needs the original destination binding and root, not only resume bytes. ## Scope and security BitTorrent v1 only; no v2/hybrid torrents, MSE/PE, or local peer discovery. Private torrents require `.torrent` metadata, not magnets. Outbound LAN addresses are blocked by default; see [networking](https://spill.rs/docs/networking/) and [private trackers](https://spill.rs/docs/private-trackers/). The [web interface and HTTP API](https://spill.rs/docs/web/) are optional and loopback-only. Use an SSH tunnel for remote access. API calls require `X-Spill-Token`; the token is readable by other local users, so it is not multi-user authentication. Prefer the CLI/Unix socket for local automation. See [limits and measured performance](https://spill.rs/docs/limits/) and [troubleshooting](https://spill.rs/docs/troubleshooting/). Do not assume unmeasured capacity or universal peer/tracker compatibility.