Install Fisherboy

Fisherboy ships as a single self-contained Docker image (ghcr.io/diegoparras/fisherboy:latest). The same image runs the API, the worker and the optional web UI; a Redis service backs the job queue.

Requirements

• Docker (Docker Desktop on Windows/Mac, or Docker Engine on Linux).
• A Redis service for the queue — included in the bundled compose files.
• Roughly 1 GB of disk for the image (it bundles Chromium for the browser tiers).
• No external services are required to start: with no ANONIMAL_URL set, the built-in regex anonymizer is used.

Fail-closed by default

With no role passwords (and no API_TOKEN or explicit dev opt-in) configured, Fisherboy rejects every request with 401. Set at least SECRET_KEY and GOD_PASSWORD before you log in.

Quick start (Docker Compose)

The fastest path — standalone, with the web UI:

git clone https://github.com/diegoparras/fisherboy.git
cd fisherboy
cp .env.example .env          # set SECRET_KEY + GOD/ANGEL/HUMAN_PASSWORD
docker compose -f docker-compose.standalone.yml up -d --build
# → open http://localhost:8000

The docker-compose.standalone.yml file brings up three services — the API (fisherboy-api, on port 8000), the worker (fisherboy-worker) and Redis (fisherboy-redis) — all on a private network.

Useful follow-ups:

docker compose -f docker-compose.standalone.yml logs -f    # follow logs
docker compose -f docker-compose.standalone.yml down       # stop

Run the published image

Don’t want to build? Pull the prebuilt image (published by GitHub Actions):

docker pull ghcr.io/diegoparras/fisherboy:latest

Run it by hand with a Redis container alongside:

docker run -d --name fisherboy-redis redis:7-alpine

docker run -d --name fisherboy-api --env-file .env \
  -e APP_MODE=standalone \
  -e REDIS_URL=redis://fisherboy-redis:6379/0 \
  -p 8000:8000 --link fisherboy-redis \
  ghcr.io/diegoparras/fisherboy:latest

docker run -d --name fisherboy-worker --env-file .env \
  -e APP_MODE=standalone \
  -e REDIS_URL=redis://fisherboy-redis:6379/0 \
  --link fisherboy-redis \
  ghcr.io/diegoparras/fisherboy:latest python -m app.worker

The API is the image’s default command (uvicorn app.main:app --host 0.0.0.0 --port 8000); the worker is started with python -m app.worker.

Minimal .env

Copy .env.example to .env and set at least:

APP_MODE=standalone
SECRET_KEY=<a long random string>
GOD_PASSWORD=<your admin password>
ANGEL_PASSWORD=<optional>
HUMAN_PASSWORD=<optional>
COOKIE_SECURE=0          # 0 for local http://localhost (no HTTPS)

Tip

Generate a key quickly: python -c "import secrets; print(secrets.token_hex(32))".

First run

1. Start the stack (docker compose -f docker-compose.standalone.yml up -d --build). The first build takes a few minutes; later starts are instant.
2. Open http://localhost:8000.
3. At the login screen, enter your GOD_PASSWORD.

Throwaway local run

For a local, never-exposed run you can skip login by setting FISHERBOY_OPEN_GOD=1 in .env — it enters as dios automatically. Never use this on anything reachable by others.

Two modes

Fisherboy runs in one of two modes, chosen by APP_MODE. The core is identical; the mode only decides whether the web UI is mounted and where document conversion is delegated.

	standalone	sidekick
Web UI	yes, its own	no, headless
Interface	UI + REST + MCP	REST + MCP
Use	self-host, personal	behind Escriba, internal network

For sidekick mode behind Escriba, use docker-compose.yml, which joins the external escriba_internal network to reach Anonimal and Escriba.

Main environment variables

Variable	Default	What it does
APP_MODE	sidekick	standalone (mounts the web UI) or sidekick (headless).
SECRET_KEY	—	Required with auth. Signs the session cookie; use the same value on every replica.
GOD_PASSWORD / ANGEL_PASSWORD / HUMAN_PASSWORD	—	Role passwords. Set at least one to enable login.
COOKIE_SECURE	1	Send the session cookie only over HTTPS. Set 0 for local http.
FISHERBOY_OPEN_GOD	0	Dev only: open access as dios with no login. Never in production.
REDIS_URL	redis://fisherboy-redis:6379/0	Queue + envelope store.
ANONIMAL_URL	—	Anonimal (inside Escriba) for full NER. Empty falls back to the built-in regex anonymizer.
MAX_FETCH_TIER	3	Escalation ceiling (0 static, 1 TLS, 2 stealth, 3 browser).
PROXIES	—	Comma/line-separated proxy pool.
MAX_JOBS_PER_MIN	60	Rate-limit of job submissions per IP.
CRAWL_MAX_PAGES	100	Hard cap of pages per job.
LLM_API_BASE_URL / LLM_API_KEY / LLM_MODEL	—	For output_format=json (LLM extraction).
ALLOW_PRIVATE_TARGETS	0	Dev/test only — disables SSRF protection. Never in production.

The full, commented list lives in .env.example in the repo. For Docker Desktop, EasyPanel and production deployment, see docs/DEPLOY.md.

Read the documentation