Skip to content

Getting started

LynxPrompt runs as one container next to PostgreSQL. You need Docker with Compose v2 (or Kubernetes for the Helm chart) and, for a real deployment, an SMTP server: the default way to sign in is a link sent by mail. The image is built for linux/amd64 and linux/arm64, so Apple Silicon, Raspberry Pi and other ARM hosts run it natively.

Docker Compose

curl -O https://raw.githubusercontent.com/GeiserX/LynxPrompt/main/docker-compose.selfhost.yml -O https://raw.githubusercontent.com/GeiserX/LynxPrompt/main/docker-compose.mailpit.yml
(umask 077; printf 'NEXTAUTH_SECRET=%s\nDB_PASSWORD=%s\nADMIN_EMAIL=you@example.com\n' "$(openssl rand -base64 32)" "$(openssl rand -hex 24)" > .env)
docker compose -f docker-compose.selfhost.yml -f docker-compose.mailpit.yml up -d

What the three lines do:

  1. Download the compose file and, for a try-out, the Mailpit file. Mailpit is a local mailbox that catches the sign-in mail so you can read the link at http://localhost:8025 without an SMTP server.
  2. Write a .env only you can read: the session secret, the database password and your own address in ADMIN_EMAIL. That address becomes the superadmin the first time it signs in.
  3. Start PostgreSQL and the app. The first start pulls the image and runs the migrations; docker compose -f docker-compose.selfhost.yml -f docker-compose.mailpit.yml logs -f lynxprompt shows Database sync complete. and then the Next.js ready line.

The app listens on http://localhost:3000. PORT=8080 in .env moves it, and APP_URL must then be the URL the browser uses (http://localhost:8080, or your domain behind a reverse proxy), because the sign-in link is built from it.

First sign-in

Open http://localhost:3000/auth/signin and enter the ADMIN_EMAIL address. LynxPrompt mails a link that is valid for 24 hours. With the Mailpit file, open http://localhost:8025 and click the link there; the dashboard opens, with Quick Actions, your blueprints, drafts and teams. That account is promoted to superadmin at that sign-in (the promotion happens whenever the signed-in address equals SUPERADMIN_EMAIL, which the compose file sets from ADMIN_EMAIL).

The dashboard after the first sign-in: the team, Quick Actions, Saved Drafts and Team Blueprints

For a real deployment, put your mail server in .env and leave the Mailpit file out of the docker compose line:

SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USER=lynxprompt
SMTP_PASSWORD=...
SMTP_FROM=lynxprompt@example.com

Never expose Mailpit: anyone who can open its port can sign in as anyone. The other ways to sign in (passkeys, GitHub or Google OAuth, SSO) are switched on in Configuration; passkeys need an account that already exists, so the first sign-in is always the mail link or OAuth.

Upgrading

Change the image tag in docker-compose.selfhost.yml to the newer release from Docker Hub and run the same docker compose ... up -d. Migrations run at start. Back up the four databases first (docker compose ... exec postgres pg_dumpall -U lynxprompt > backup.sql). Uploaded images live in the uploads volume, which survives the upgrade.

Helm chart (Kubernetes)

helm repo add lynxprompt https://geiserx.github.io/LynxPrompt
helm install lynxprompt lynxprompt/lynxprompt

The chart bundles PostgreSQL by default, or points at an external one with externalDatabase.*. Its values are documented in the chart README and listed in values.yaml. The chart is also on ArtifactHub.

Install channels

What Channel Command or link
Web app Docker Hub drumsergio/lynxprompt (tags)
Web app Helm helm repo add lynxprompt https://geiserx.github.io/LynxPrompt
Web app Hosted instance lynxprompt.geiser.cloud, no install
CLI lynxp npm npm install -g lynxprompt
CLI lynxp Homebrew (macOS, Linux) brew install GeiserX/lynxprompt/lynxprompt
CLI lynxp Chocolatey (Windows) choco install lynxprompt
CLI lynxp AUR (Arch) lynxprompt (still 2.1.1 for now; npm and Homebrew carry the current version)
CLI lynxp Snap snap install lynxprompt
CLI lynxp Binaries attached to each release
VS Code Marketplace LynxPrompt.lynxprompt, or ext install LynxPrompt.lynxprompt
CI GitHub Action lynxprompt-action
AI assistants MCP server lynxprompt-mcp

After installing the CLI: lynxp config set-url https://lynxprompt.example.com for your own instance (the default, which lynxp config show prints, is the hosted instance at https://lynxprompt.geiser.cloud), then lynxp login. See Usage.