Self-hosted setup

Prerequisites

• Docker and Docker Compose (or Node 20+ for non-Docker)
• Postgres 16+ (or use the bundled Postgres in docker-compose)
• For UmbrelOS: an Umbrel-compatible device (e.g. Raspberry Pi, Umbrel Home)
• For Clovyr.io: a Clovyr account and app slot for the Paranor image

Quick start (Docker, generic)

1. 1. Clone and env — Clone the repo, copy .env.example to .env.local. Set at least NEXTAUTH_SECRET, DATABASE_URL (or use default for local Postgres), and ADMIN_PASSWORD.
2. 2. Start Postgres and run migrations — Run docker-compose up -d postgres. Set DATABASE_URL (e.g. postgresql://paranor:paranor@localhost:5432/paranor) and run the project’s init/migration script (e.g. ./scripts/init-db.sh or migrations in order per MIGRATIONS_ORDER.md).
3. 3. Start Paranor — Run docker-compose up -d paranor. Open http://localhost:3000 (or your public URL). Verify with GET /api/agent/health (expect 200 and status operational).

UmbrelOS-specific

If Paranor is in the Umbrel app store, install it from the store and set NEXTAUTH_SECRET (and optionally NEXTAUTH_URL) in the app settings. For manual/custom app: add the repo’s umbrel/ folder as a custom app source in Umbrel; set NEXTAUTH_SECRET (e.g. openssl rand -base64 32).

First-run migrations on Umbrel: After install, Postgres must be seeded. You can (1) SSH into Umbrel and run migrations from the host with the correct DATABASE_URL, or (2) run a one-off migration container that connects to the Umbrel Postgres and executes the migration scripts in order (see the project’s SELF_HOST.md and umbrel/README.md for exact commands and MIGRATIONS_ORDER.md).

To appear in the Nexus, set PARANOR_NEXUS_OPT_IN=true in app settings (if your build supports it) and enable “Discoverable in Nexus” in Paranor → Profile.

Clovyr.io

Deploy the same Paranor Docker image (or Clovyr’s app packaging) to Clovyr.io. Set NEXTAUTH_URL to your Clovyr app URL (e.g. https://your-app.clovyr.io). Use Clovyr’s Postgres or your own DATABASE_URL. Run migrations as in the Quick start. For Nexus discovery, set PARANOR_NEXUS_URL to https://paranor.app and opt in via Profile in the app.

Clovyr does not support compute workers; that option is for UmbrelOS home servers. See the project's SELF_HOST.md (Clovyr section) or clovyr/README.md for details.

Key environment variables

Required: DATABASE_URL, NEXTAUTH_SECRET, ADMIN_PASSWORD. For production cron: CRON_SECRET. For Nexus opt-in: PARANOR_NEXUS_URL (e.g. https://paranor.app); optional PARANOR_NEXUS_REGISTER_SECRET from the Paranor team for push auth. Full list (L402, Fedimint, etc.) is in the repo’s SELF_HOST.md and .env.example.

After setup

Use the Level 1 Self-Host Test Kit (see the project’s scripts/test/selfhost/README.md) to validate install, security, and Nexus connectivity. From your Paranor.app account you can also run connectivity checks to confirm your self-hosted instance appears in discovery after sending a heartbeat.