Skip to content

Install Numi

Set up a local or Docker instance, create the first administrator account, and verify that you can send a chat message.

Already have access to a running instance? Go to First chat.

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

1. Choose how to run it

Both routes need Git, OpenSSL to generate a secret, and a model provider API key or access to a local model server. The steps below use OpenRouter because the packaged models use it.

Route Install on the host
Local process Python 3.12+, uv 0.9.17+, and Make
Docker Docker Engine and Docker Compose v2

For local Python tools that need packages such as pandas or matplotlib, also install Deno. Docker includes it. Basic chat and eligible dependency-free code execution do not require Deno.

2. Get the code and configure it

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

Copy the example only for a new installation. Keep an existing .env when updating or continuing an earlier setup.

Generate a secret in your terminal:

openssl rand -hex 32

Open .env in an editor and set these values. Paste the generated secret as the value of AUTH_SECRET_KEY:

AUTH_SECRET_KEY="paste-the-generated-secret-here"
OPENROUTER_API_KEY="your-openrouter-api-key"
MEMORY_SUMMARY_MODEL=inherit
CHAT_TITLE_MODEL=inherit

The authentication secret must contain at least 32 characters. Keep it private and stable across restarts.

The two inherit settings make background memory and title tasks use the catalog default. You can select separate models for those tasks later.

Using another provider? Configure its credentials or endpoint using Providers and endpoints, then add an entry on the Models page after signing in. Credentials alone do not add models to the selector. That guide also covers background memory and chat-title models.

3. Start the instance

From the repository directory:

uv sync
make run-web

The first start restores pinned browser assets and applies database migrations. Keep the terminal open while using Numi. Stop it with Ctrl+C.

In docker-compose.yml, remove the two REWE credential volume entries unless you are supplying those integration files. Then prepare the bind-mount paths and start the service:

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 image includes Python, Deno, and document-processing tools. You do not need uv on the host. Ctrl+C stops following logs; the service keeps running. See Docker deployment for management commands and persistent data paths.

Open http://localhost:4567/login. Once startup finishes, you should see the sign-in page. A health check is also available at http://localhost:4567/health.

4. Create your account and send a message

  1. Choose Sign up from the sign-in page.
  2. Enter a username and password, then select Sign Up. By default, the password needs at least 12 characters, uppercase and lowercase letters, a number, and a supported symbol shown by the form.
  3. Follow First chat to choose a model and send a message.

The first account becomes the administrator. On an empty database, signup is temporarily available even when registration is disabled; it closes after that first account unless an administrator enables it.

Setup is complete when a model responds to your message. Continue with Use Numi, or Run Numi to configure the instance. Before exposing it publicly, follow the deployment and security guidance.

If setup fails

Symptom Check
Startup rejects AUTH_SECRET_KEY Set a secret with at least 32 characters in the repository's .env.
The model selector is empty Configure the provider, restart, and add or enable a matching entry on the Models page.
A model returns an authentication error Check the provider key and endpoint privately in your editor.
Port 4567 is in use Stop the process using it, or use NUMI_CHAT_PORT=8080 docker compose up -d for Docker. There is no PORT override for make run-web.
The app cannot write its data Check ownership of chats.db, state/, and logs/; see Docker deployment.
Code execution is unavailable Check deno --version for package-based execution and the tool requirements.

For an existing database that needs attention, use Database migrations. Keep the database and its backup while diagnosing the problem.