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.
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¶
Only copy .env.example on a fresh install; keep your existing .env when
updating.
Generate a random 32-byte secret in your terminal:
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_KEYmust be at least 32 characters long. Keep it private and unchanged across restarts so sessions and encrypted credentials remain valid.- Setting
MEMORY_SUMMARY_MODEL=inheritandCHAT_TITLE_MODEL=inheritmakes 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:
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¶
- Click Sign up on the sign-in screen.
- 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.
- 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.