Quickstart¶

See also Install and First run.

Keprix has two install paths. The CLI / TUI path (Option A) is primary for day-to-day agent use. Docker Compose (Option B) is the full web stack path (UI + API + Postgres + Redis and related services).

Option A: curl installer (CLI / TUI)¶

See Install for the full guide.

curl -fsSL https://raw.githubusercontent.com/malike2356/keprix/main/scripts/install.sh | bash

The public GitHub repository is anonymously readable. This command follows the development channel. For immutable stable releases, download and inspect scripts/install-release.sh, then run it with an exact --version.

Next steps after install:

keprix --version
keprix setup
keprix tui

Option B: Docker Compose (full web stack)¶

Use this when you want the browser workspace plus the API and databases on one machine.

Prerequisites¶

You do not need Python or Node.js on the host. Everything runs in containers.

Start the stack¶

git clone https://github.com/malike2356/keprix.git
cd keprix
cp .env.example .env
# Set at least one of ANTHROPIC_API_KEY, OPENAI_API_KEY, or GEMINI_API_KEY
docker compose -f docker/docker-compose.yml up -d --build

Copy values from .env.example. Leave unused keys empty; set at least one provider key before first run (for example ANTHROPIC_API_KEY= or OPENAI_API_KEY=your-key-here). Do not paste real secrets into docs or tickets.

On Linux hosts, do this first (verified 2026-09-06 against a genuinely fresh clone with no pre-existing ~/.keprix). docker/docker-compose.yml bind-mounts ~/.keprix into the backend container; if that directory does not already exist, the Docker daemon auto-creates it as root, and the container's non-root keprix user then fails on its very first write with PermissionError: [Errno 13] Permission denied. Avoid this by creating the directory yourself, as yourself, and telling the container to match your UID/GID before the first up:

mkdir -p ~/.keprix
echo "KEPRIX_UID=$(id -u)" >> .env
echo "KEPRIX_GID=$(id -g)" >> .env

(Verified reproducing and fixed on Linux with the native Docker Engine. Docker Desktop on macOS/Windows maps file ownership differently and has not been independently verified either way here - running the same two lines before up is harmless if you are unsure.)

Compose depends_on (default full stack): the frontend waits until the backend healthcheck passes; the backend waits until postgres and redis are healthy. That is the default docker/docker-compose.yml behavior.

Marketing-only frontend on Contabo/Cloudflare is optional and not the default Compose stack. See Cloud deploy and VPS deploy. Public origin notes may expand later.

Wait until healthy¶

docker compose -f docker/docker-compose.yml ps

Containers should show healthy or running. The backend runs migrations on startup; wait for health before opening the UI.

curl -s http://127.0.0.1:3333/api/health
# Expect JSON with a status field when the API is up

Setup wizard¶

Open http://localhost:3000. The first-run wizard covers instance name, admin account, LLM provider confirmation, and optional channels. After Finish setup, use Chat in the sidebar to talk to the agent.

Stop and update¶

docker compose -f docker/docker-compose.yml down

Data lives in Docker volumes; stop/restart keeps it. Full reset (deletes volumes):

docker compose -f docker/docker-compose.yml down -v

Update:

git pull
docker compose -f docker/docker-compose.yml up -d --build

Migrations apply on backend startup.

Port conflicts¶

In .env:

FRONTEND_PORT=3001
BACKEND_PORT=3334

Then restart the stack.

Production VPS¶

For Compose behind Caddy on a VPS, see VPS deploy. Compose service reference: Docker Compose reference.

Troubleshooting¶

Logs

docker compose -f docker/docker-compose.yml logs backend
docker compose -f docker/docker-compose.yml logs frontend

Database connection errors

On very slow hosts, restart the backend after Postgres is healthy:

docker compose -f docker/docker-compose.yml restart backend

No LLM responses

1. Confirm .env has at least one provider key set.
2. docker compose -f docker/docker-compose.yml restart backend
3. In the wizard or admin UI, confirm the default provider matches that key.

PermissionError: [Errno 13] Permission denied on backend startup

~/.keprix was auto-created by Docker as root before you set ownership. Stop the stack, fix ownership, and set the UID/GID mapping from "Start the stack" above, then rebuild:

docker compose -f docker/docker-compose.yml down
sudo chown -R "$(id -u):$(id -g)" ~/.keprix
echo "KEPRIX_UID=$(id -u)" >> .env
echo "KEPRIX_GID=$(id -g)" >> .env
docker compose -f docker/docker-compose.yml up -d --build

Port 3000 in use

Set FRONTEND_PORT=3001 and open http://localhost:3001.

Slow first build

The first --build downloads base images and compiles the frontend. Later starts are much faster.

Without Docker¶

CLI/TUI without Compose: Install. Manual contributor setup: Manual install.

Next steps¶