Skip to content

Install Numi

Set up a local or Docker instance, create the first administrator account, and send your first chat message.

Already have access to a running instance? Jump straight to Your First Chat.

Unpack a server, connect a model provider, and receive a chat reply.

1. Choose how to run it

Both setups need Git, OpenSSL (to generate an authentication secret), and either a model provider API key or a local OpenAI-compatible server. The quick setup below uses OpenRouter because the default model catalog is preconfigured for it.

Route Host prerequisites
Local process Python 3.12+, uv 0.9.17+, and Make
Docker Docker Engine and Docker Compose v2

For local Python tool calls that import packages such as pandas or matplotlib, also install Deno. The Docker image already includes Deno. Basic chat and dependency-free Python scripts (which run on Monty) work without Deno.

2. Clone and configure .env

git clone https://github.com/EvickaStudio/numi-chat.git
cd numi-chat
cp .env.example .env

Only copy .env.example on a fresh install; keep your existing .env when updating.

Generate a random 32-byte secret in your terminal:

openssl rand -hex 32

Open .env in your editor and set AUTH_SECRET_KEY and your provider key:

AUTH_SECRET_KEY="paste-the-generated-secret-here"
OPENROUTER_API_KEY="your-openrouter-api-key"
MEMORY_SUMMARY_MODEL=inherit
CHAT_TITLE_MODEL=inherit
  • AUTH_SECRET_KEY must be at least 32 characters long. Keep it private and unchanged across restarts so sessions and encrypted credentials remain valid.
  • Setting MEMORY_SUMMARY_MODEL=inherit and CHAT_TITLE_MODEL=inherit makes background memory and title tasks use your catalog's default model. You can point them at a cheaper utility model anytime.

Using a different provider? Configure its credentials or base URL using Configure Multiple Providers, then enable or add a matching model on the Models page after signing in.

3. Start the server

From the repository root:

uv sync
make run-web

The first start restores pinned browser assets and applies database migrations automatically. Stop the server anytime with Ctrl+C.

In docker-compose.yml, remove the two REWE certificate volume mounts unless you use those optional grocery files. Then create the host bind-mount paths and start the container:

mkdir -p state/uploads state/generated_files state/avatars logs
touch chats.db
docker compose up --build -d
docker compose logs -f numi-chat

The container image includes Python, Deno, and document tools. Press Ctrl+C to stop following the logs while the service stays running in the background. See Run with Docker for day-to-day commands and backup paths.

Open http://localhost:4567/login in your browser. You can also check http://localhost:4567/health to confirm the server is up.

4. Create your administrator account

  1. Click Sign up on the sign-in screen.
  2. Enter a username and password and click Sign Up. By default, passwords require at least 12 characters with uppercase and lowercase letters, a number, and a symbol.
  3. Follow Your First Chat to pick a model and send a test message.

The very first account created on an empty database becomes the instance administrator. Even when open registration is disabled, signup stays open until that first administrator account is created, then closes automatically unless enabled in Admin settings.

Before exposing your instance to a network or the internet, review Reverse proxy setup and the Security model.

Troubleshooting first startup

Symptom What to check
Startup rejects AUTH_SECRET_KEY Make sure AUTH_SECRET_KEY in .env is at least 32 characters long.
The model selector is empty Check that your provider key is set in .env, restart the server, and make sure a model for that provider is enabled on the Models page.
Provider returns an authentication error Verify the API key and base URL in .env or under Settings -> API Keys.
Port 4567 is already in use Stop the other process, or run NUMI_CHAT_PORT=8080 docker compose up -d when using Docker.
Permission errors writing data Check file ownership on chats.db, state/, and logs/ (see Run with Docker).
Package-based Python code fails Run deno --version on the host and check Tools reference.

If an existing database needs manual migration recovery, see Database migrations.