Neptune

A headless BitTorrent client.

Only 64-bit systems are supported.

Pre-built static binaries are available in GitHub Releases.

Pre-built static binaries have zero system library dependency and do not require glibc. Minimum OS version requirements by the Go toolchain:

• Linux: kernel >= 3.1
• Windows: Windows 10 / Windows Server 2016 or higher
• macOS: macOS 12 Monterey or newer

Pre-built Docker image: ghcr.io/trim21/neptune

Platforms: linux/amd64, linux/arm64.

Neptune stores data in two directories:

The session directory contains these sub-directories:

services:
  neptune:
    image: ghcr.io/trim21/neptune:master
    init: true
    environment:
      NEPTUNE_WEB_SECRET_TOKEN: "a-secret-token-change-me"
      NEPTUNE_SESSION_PATH:    "/var/lib/neptune"
      NEPTUNE_CONFIG_FILE:     "/var/lib/config/neptune.toml"
      # Optional overrides (all have sensible defaults):
      # NEPTUNE_WEB:             "0.0.0.0:8002"
      # NEPTUNE_P2P_PORT:        "50047"
      # NEPTUNE_LOG_LEVEL:       "info"
      # NEPTUNE_LOG_JSON:        "false"
      # NEPTUNE_LOG_SAVE_TO_FILE:"true"
      # NEPTUNE_DEBUG:           "false"
    network_mode: host # required for P2P connectivity
    healthcheck:
      test: [
        "CMD",
        "/usr/local/bin/wget",
        "--spider",
        "--no-verbose",
        "http://127.0.0.1:8002/healthz",
      ]
      interval: 10s
      timeout: 3s
      start_period: 10s
    volumes:
      # Session data (torrents, resume, logs) — persist this
      - ./data/neptune/:/var/lib/neptune/

      # Downloaded files — persist this
      - ./data/downloads/:/downloads/

      # Config file — mount read-only
      - ./config.toml:/var/lib/config/neptune.toml:ro

  flood:
    image: ghcr.io/trim21/flood:neptune
    network_mode: host
    command:
      - --port=4008
      - --noauth
      - --neptune-url=http://127.0.0.1:8002/json_rpc
      - --neptune-token=a-secret-token-change-me
    volumes:
      - ./data/neptune/:/var/lib/neptune/
      - ./data/downloads/:/downloads/

Key points for deployment:

1. Network mode must be host — Neptune needs direct access to all ports for P2P communication.
2. Web secret token (NEPTUNE_WEB_SECRET_TOKEN) secures the JSON-RPC API. Set it to a strong random value and keep it consistent across restarts. If left empty, a new token is generated on every startup.
3. Volume mounts — at minimum, persist the session directory and your downloads directory. The config file is optional but recommended.
4. The Flood volume mounts must mirror Neptune's so Flood can read torrent files for the Web UI.

Create a config.toml next to your compose file:

[application]
download-dir = "/downloads"
p2p-port = 50047
fallocate = true
# optional overrides:
# max-http-parallel = 100
# num-want = 50
# global-connections-limit = 50
# global-upload-slots = 64
# global-download-speed-limit = 0  # bytes/sec, 0 = unlimited
# global-upload-speed-limit = 0    # bytes/sec, 0 = unlimited

All config keys are optional:

Install Go >= 1.25 and go-task.

git clone https://github.com/trim21/neptune.git
cd neptune

# Build for your platform (release mode):
task release:linux:amd64   # or release:linux:arm64, release:darwin:amd64, etc.

Available build targets:

• release:linux:amd64
• release:linux:arm64
• release:darwin:amd64
• release:darwin:arm64
• release:windows:amd64
• release:windows:arm64

Run ./neptune --help to see all flags.

task lint          # run linter
task test          # run tests
task gen           # run code generation (stringer, protobuf)
task dev --watch   # build and auto-restart on code changes
task release       # build release binaries for all platforms
task --list-all    # list all available tasks

This project is mixed licensed. Most code is GPL v3. Some files are derived from other projects and retain their original licenses:

• Files copied from anacrolix/torrent: MPL-2.0
• Files in internal/web/jsonrpc/ derived from swaggest/jsonrpc: MIT

License information is noted in each file header.