Pullbox

Modern comic book management and acquisition for self-hosted libraries.

Pullbox helps discover, download, organize, and catalog digital comic collections. It follows the familiar self-hosted media-app model: connect metadata, indexers, download clients, and a library path, then let the app keep wanted issues moving through search, download, post-processing, and library organization.

Quick Start With Docker

Pullbox listens on port 8585 and uses four main container paths:

Pre-Run Setup

Pullbox was created with maximum application / image security in mind and is implemented using a Docker Hardened Image. Based on this, there are a few requirements that must be met prior to spinning up the container.

First, you must create or choose host folders for Pullbox data, your comics library, completed downloads, and import sources. The /data folder should be durable local storage because it contains SQLite, config.xml, logs, and backups.

If the above folders do not exist create them:

sudo mkdir -p /path/to/pullbox-appdata /path/to/comics /path/to/shared-downloads /path/to/imports/remote-drop

Pullbox-created files and folders are owned by the hardened-image runtime UID/GID 65532:65532. On Linux hosts, create a matching host group and add your user to it before first startup so you can browse Pullbox-created files from the host:

if ! getent group 65532 >/dev/null; then
  sudo groupadd --gid 65532 pullbox-runtime
fi
sudo usermod -aG "$(getent group 65532 | cut -d: -f1)" "$USER"

Log out and back in after usermod so the new group membership is active.

Once created or chosen, make each folder writable by the runtime UID/GID 65532:65532. On Linux hosts with ACL support, this avoids changing ownership of existing media:

sudo setfacl -m u:65532:rwx -m d:u:65532:rwx /path/to/pullbox-appdata
sudo setfacl -m u:65532:rwx -m d:u:65532:rwx /path/to/comics
sudo setfacl -m u:65532:rwx -m d:u:65532:rwx /path/to/shared-downloads
sudo setfacl -m u:65532:rwx -m d:u:65532:rwx /path/to/imports
sudo setfacl -m u:65532:rwx -m d:u:65532:rwx /path/to/imports/remote-drop

For dedicated Pullbox-only folders, ownership is also acceptable:

sudo chown -R 65532:65532 /path/to/pullbox-appdata /path/to/comics /path/to/shared-downloads /path/to/imports

Docker Run

docker run -d \
  --name pullbox \
  --restart unless-stopped \
  -p 8585:8585 \
  -e TZ=America/New_York \
  -e PULLBOX_DB_URL=sqlite+aiosqlite:////data/pullbox.db \
  -e PULLBOX_SQLITE_JOURNAL_MODE=WAL \
  -e PULLBOX_LIBRARY_ROOT=/comics \
  -e PULLBOX_COVERS_DIR=/comics/.covers \
  -v /path/to/pullbox-appdata:/data \
  -v /path/to/comics:/comics \
  -v /path/to/shared-downloads:/downloads \
  -v /path/to/imports:/imports \
  ghcr.io/pullboxapp/pullbox:latest

Open http://localhost:8585 and complete first-run setup.

For manual folder imports, place files under your host import staging folder such as /path/to/imports/remote-drop, then select /imports/remote-drop inside Pullbox.

Docker Compose

If you do not have a shared Docker Compose .env file, copy the production .env example and edit the paths:

cp docker/.env.example .env

If you already have a shared Docker Compose .env file, add these variables to that existing file instead of creating a new one:

TZ=America/New_York
PULLBOX_HOST_PORT=8585
PULLBOX_DATA_PATH=/path/to/pullbox-appdata
COMICS_PATH=/path/to/comics
DOWNLOADS_PATH=/path/to/shared-downloads
IMPORTS_PATH=/path/to/imports
IMPORTS_DROP_PATH=/path/to/imports/remote-drop

Use the below example to create a Docker Compose file:

services:
  pullbox:
    image: ghcr.io/pullboxapp/pullbox:latest
    container_name: pullbox
    restart: unless-stopped
    ports:
      - "${PULLBOX_HOST_PORT}:8585"
    environment:
      TZ: ${TZ}
      PULLBOX_DB_URL: sqlite+aiosqlite:////data/pullbox.db
      PULLBOX_SQLITE_JOURNAL_MODE: WAL
      PULLBOX_LIBRARY_ROOT: /comics
      PULLBOX_COVERS_DIR: /comics/.covers
    volumes:
      - ${PULLBOX_DATA_PATH}:/data
      - ${COMICS_PATH}:/comics
      - ${DOWNLOADS_PATH}:/downloads
      - ${IMPORTS_PATH}:/imports

To start pullbox:

docker compose -f docker/docker-compose.yml --env-file .env up -d

Open http://localhost:8585 and complete first-run setup.

Docker Environment Variables

The Docker run and compose examples above are intentionally minimal. For most installs, configure the rest of Pullbox in the web UI. If you want a setting to be managed by the container environment, add the value to your .env file and pass it through under the service environment: block. For docker run, add the same value with -e.

Environment-managed values can override UI/database settings and may appear read-only or runtime-managed inside Pullbox.

Features

• Comic series and issue management.
• ComicVine metadata integration.
• Newznab, Torznab, Prowlarr, and Jackett indexer support.
• SABnzbd, NZBGet, qBittorrent, Transmission, and Deluge download clients.
• Manual and automated wanted-issue search.
• Search history, rejected results, and blocklist support.
• Post-processing for completed downloads.
• Library scanning, matching, renaming, conversion, and integrity utilities.
• Responsive single-page comic reader for CBZ, CBR, CB7, CBT, and PDF files.
• Intervention queue for ambiguous matches.
• Health checks, diagnostics, logs, backups, and audit trail.
• Server-rendered UI with HTMX, Alpine.js, and Tailwind CSS.

Development

Contributor setup, validation commands, coding standards, and workflow details live in the repo docs:

• CONTRIBUTING.md
• docs/development/ARCHITECTURE_OVERVIEW.md
• docs/development/CODE_STANDARDS.md
• docs/development/DATABASE_STANDARDS.md
• docs/development/SECURITY_STANDARDS.md
• docs/development/INFRASTRUCTURE.md
• docs/development/DESIGN_SYSTEM.md
• docs/features/comic-reader.md

Security

Private vulnerability reporting and deployment security guidance are covered in SECURITY.md.

License

Pullbox is licensed under GPL-3.0-or-later. See LICENSE for details.