Configuration

CLI

The private-gpt CLI covers the full service lifecycle: starting the HTTP server, launching background workers, and running connected apps like Claude Code.

private-gpt <command> [flags]
Commands:
  serve     Start the HTTP server
  worker    Start a background worker process
  run       Launch a connected app (claude-code, openclaw, custom)
  help      Show help for any command

serve

Starts the uvicorn HTTP server.

$private-gpt serve [flags]
FlagDefaultDescription
--host0.0.0.0Bind address
--portfrom settingsHTTP port
--reloadoffEnable auto-reload for development
--log-levelinfodebug | info | warn | error
--pid-file—Write PID to file (for systemd / launchd)

Examples:

$# Start with defaults
$private-gpt serve
$
$# Development mode with auto-reload
$private-gpt serve --reload --log-level debug
$
$# Production with PID file for process supervision
$private-gpt serve --pid-file /var/run/private-gpt.pid

PID file behavior: if --pid-file is given and the file already exists with a live process, the command exits with code 1 and prints the existing PID. On SIGTERM the PID file is removed.

worker

Starts the Celery worker stack. All behaviour is controlled through environment variables — no CLI flags.

$private-gpt worker

The worker process manages up to three sub-processes depending on PGPT_WORKER_MODE:

PGPT_WORKER_MODEWhat starts
mixed (default)Celery worker + Flower UI
workerCelery worker only
flowerFlower UI only

Examples:

$# Default: worker + Flower UI
$private-gpt worker
$
$# Worker only, no Flower
$PGPT_WORKER_MODE=worker private-gpt worker
$
$# Custom concurrency and queues
$PGPT_CELERY_QUEUES=ingest,chat PGPT_CELERY_CONCURRENCY=4 private-gpt worker

run

Launches a connected app as a managed child process, automatically injecting the server connection details.

See the Integrations section for app-specific setup guides.

$private-gpt run <app> [flags] [-- <app-args>]
FlagDefaultDescription
--attach / --no-attachauto (TTY detected)Attach stdin/stdout
--detachoffRun in background, print run ID
--session <id>—Resume a previous app session
--model <id>llm.default_modelModel name (forwarded via env)
--auto-approveoffSkip confirmations (CI mode)
--no-serveroffSkip server detection and auto-start

Server auto-start: before launching the app, private-gpt run checks /health. If the server is not reachable it starts one automatically and waits up to 60 s. Pass --no-server to skip this — useful when the server is managed externally (systemd, Docker).

help

Show help for any command:

$private-gpt help
$private-gpt help serve
$private-gpt serve --help

Unknown commands print a suggestion:

$ private-gpt srve
Unknown command: 'srve'. Did you mean: 'serve'?