Install with Docker

This guide runs the Priompt server from its published container image, with an admin token and a volume that keeps your prompts across restarts. The same steps work on Linux, on macOS with Docker Desktop or OrbStack, and on Windows with Docker Desktop.

The image ghcr.io/priompt/priompt is published for linux/amd64 and linux/arm64, tagged per release (such as :v0.7.4) and :latest. It exposes 8443 (gRPC), 2112 (metrics), and 4222 (NATS). The server runs as the non-root user priompt (uid 10001) and keeps its database in /data/priompt.db.

Prerequisites

Before you begin, make sure you have:

• Docker Engine or Docker Desktop: see Get Docker.
• A POSIX shell: the commands use \ line continuations. On Windows, use Git Bash or WSL.

1. Create an admin token

To create a token that clients send to the server:

1. Generate a random token with the image itself:

   docker run --rm ghcr.io/priompt/priompt:v0.7.4 gen-token

   Output

   e65647c3fac5363603d4bc5b302bef10523dd67425efcb10a1fcc433c71b3a14

2. Keep the token somewhere safe. The next step calls it <token>.

2. Start the server

To start the server in the background:

1. Run the image with the token and a named volume:

   docker run -d --name priompt --restart unless-stopped \
     -p 8443:8443 \
     -v priompt-data:/data \
     -e PRIOMPT_TOKEN=<token> \
     -e PRIOMPT_SEED=false \
     ghcr.io/priompt/priompt:v0.7.4

   Replace <token> with the token from step 1.

The flags work as follows:

• -e PRIOMPT_TOKEN: Every request must carry this token. The server treats it as an admin token with write access.
• -e PRIOMPT_SEED=false: Skips the demo prompt the server otherwise stores on first start.
• -v priompt-data:/data: Keeps the database on the priompt-data volume, so it survives removing the container.

To pass server flags, add serve and the flags after the image name. Arguments after the image name replace the default command, serve.

Upgrading from v0.7.2 or earlier

Older images ran as root, so files they wrote to a volume or bind mount are owned by root, and publishing to v0.7.3 or later fails with code = Internal desc = publish failed while the server logs attempt to write a readonly database. Fix the ownership once before you start the new image:

docker run --rm -v priompt-data:/data alpine chown -R 10001:10001 /data

Older images also wrote the database outside /data unless you passed serve -db /data/priompt.db. If you didn't, copy the database out of the old container before you remove it. Find it with docker exec priompt find / -name priompt.db -not -path '/proc/*'.

Pin a version tag as shown. Use :latest only to try things out.

3. Check the server

To check that the server is running:

1. Read the log:

   docker logs priompt

   Output

   2026/10/18 18:27:16 priompt v0.7.4 (b9072abfc4b0fb10f8e42ac1316fd4ea12462797) serving on :8443 (tls=false mtls=false auth=1-token cache=mem embed=lexical(offline) nats=127.0.0.1:4222 metrics=:2112 ratelimit=0/s)
   2026/10/18 18:27:16 metrics on :2112/metrics

   auth=1-token means the server requires your token.

2. List the prompts with the CLI inside the container:

   docker exec priompt priompt list

   A new server has no prompts, so the command prints nothing and exits with status 0. The CLI inside the container reads PRIOMPT_TOKEN from the container's environment, so it's authorized.

Run ops commands

The image includes the whole priompt CLI. Run any command with docker exec. Commands run in /data, so they find the database without -db. Pass output paths under /data so they land on the volume.

To back up the store and copy the backup to the host:

1. Write the backup inside the container:

   docker exec priompt priompt backup -out /data/snapshot.jsonl

   Output

   backed up 1 prompts, 1 commits, 1 branch pointers

2. Copy it out:

   docker cp priompt:/data/snapshot.jsonl .

See Storage and backups for restore, and the priompt CLI reference for every command.

Build the image with Compose

To run unreleased changes, build the image from a clone of the server repo with Docker Compose. The repo's docker-compose.yml holds the whole configuration, and the other Go modules come from the module proxy.

The Compose file publishes NATS on 0.0.0.0:4222 inside the container. The server refuses to bind NATS off loopback without a NATS token, so the token is required.

To build and start the server with Compose:

1. Clone the server repo:

   git clone https://github.com/priompt/priompt.git
   cd priompt

2. Create a .env file next to docker-compose.yml, and keep it out of git:

   .env

   PRIOMPT_TOKEN=<token>
   PRIOMPT_NATS_TOKEN=<nats-token>

   Replace <token> with an admin token and <nats-token> with a second token, both from gen-token.

3. Build and start the server:

   docker compose up --build -d

4. Check the log:

   docker compose logs priompt

   Output

   priompt-1  | 2026/10/18 04:44:58 seeded demo prompt priompt://acme/onboarding/welcome
   priompt-1  | 2026/10/18 04:44:58 priompt dev (unknown) serving on :8443 (tls=false mtls=false auth=1-token cache=mem embed=lexical(offline) nats=0.0.0.0:4222 metrics=:2112 ratelimit=0/s)
   priompt-1  | 2026/10/18 04:44:58 metrics on :2112/metrics

   A local build reports its version as dev. Without PRIOMPT_NATS_TOKEN, the log shows -nats-addr 0.0.0.0:4222 is not loopback instead, and the container restarts.

What docker-compose.yml configures

The Compose file binds gRPC on all interfaces and keeps metrics and NATS on the host's loopback. Every setting is an environment variable that you can set in .env:

Name	Description
PRIOMPT_TOKEN	Admin bearer token. Blank turns authentication off.
PRIOMPT_NATS_TOKEN	The broker's own full-rights credential. Required by this file. Agents subscribe with their API token instead.
PRIOMPT_JWKS_URL	The priompt-auth /jwks URL. Blank turns JWT authentication off.
PRIOMPT_EMBED_URL, PRIOMPT_EMBED_MODEL, PRIOMPT_EMBED_KEY	Embedding endpoint for the semantic diff. Blank uses the offline lexical embedder.
PRIOMPT_REDIS_URL	Shared cache. Blank uses an in-process cache.
PRIOMPT_ENCRYPTION_KEY	Base64 of 32 random bytes. Encrypts prompts at rest.

The command list passes -db=/data/priompt.db, -cache-ttl=30s, and commented-out TLS and tokens-file flags. See Server configuration for every flag.

Other setups

• Real embedding model: the repo's docker-compose.tei.yml overlay adds a local model. See Use a real embedding model.
• PostgreSQL, Redis, and more than one node: see Scale to multiple nodes.
• TLS and tokens files: see Secure a server.

Next steps

• Production checklist: set what a server needs before it takes real traffic.
• Client SDKs: connect an agent with PRIOMPT_URL=priompt://<token>@<your-host>:8443.
• Quickstart: fetch a prompt and watch a change arrive.