What you need
2 GB RAM · 2 CPU cores · 10 GB free disk
4 GB RAM · 4 CPU cores · 20 GB free disk
During setup you choose how much the server may use, recommended, minimum or no limits, and you can change it later.
- Docker with Compose: Docker Desktop on Mac and Windows, Docker Engine on Linux.
- git to download Kelo.
- uv the Python tool that runs Kelo's setup command,
assistant. uv fetches the right Python by itself. - API key for the AI model you want.
Step by step
Run every command in a terminal, inside the Kelo folder you downloaded.
-
Download Kelo
git clone https://github.com/kelo-chat/kelo-server kelo cd kelo -
First-time setup
uv run assistant setupIt asks a few questions:
- The assistant's browser: Chromium (the default, open source) or Google Chrome.
- How much the server may use: recommended, minimum or no limits.
Any other optional questions can stay at their defaults.
Your answers go into a
.envfile in the folder, along with two new secrets: the server's access password (ASSISTANT_TOKEN) and the key that locks the keys you save (ASSISTANT_SECRET_KEY). Keep that file to yourself and back it up: lose that key and you'll have to enter your saved keys again. -
Start the server
docker compose up -d --buildThe first build takes a few minutes. By default the server only listens inside the computer it runs on (127.0.0.1:8080).
-
Add your AI model key
Add the API key for the AI model you want in the app's settings, or put it in
.env(for exampleOPENROUTER_API_KEY=…). -
Make it reachable from outside
The easiest way is a
<name>.kelo.chataddress, offered for now. Availability and terms may change.uv run assistant connect kelo --name yourname uv run assistant connect statusstatusshows the address and checks that it really reaches your server. For other ways, see the table below. -
Connect your phone
uv run assistant phone addA QR code appears in the terminal. Scan it from the connect screen in the Kelo app and you're done. The link works once, for 10 minutes; run the command again for each extra phone.
Ways to reach it from outside
One way at a time: picking a new one turns the old one off for you.
| Way | Command | Keep in mind |
|---|---|---|
| Kelo address (offered for now) | assistant connect kelo --name NAME | Easiest: no router changes. Traffic uses https through a Cloudflare Tunnel. |
| Tailscale (private) | assistant connect tailscale | Most private: nothing is public. Every phone needs the Tailscale app on the same account. |
| Tailscale Funnel (public) | assistant connect funnel | Public https without a domain, encrypted all the way to the server. Ports 443, 8443 and 10000 only; it's in beta, with bandwidth limits. |
| Your domain on Cloudflare | assistant connect cloudflare --domain example.com | Uses a domain on your own Cloudflare account. Needs cloudflared on the computer the server runs on. |
| Your domain, direct | assistant connect domain --host me.example.com --direct | Nothing in between. Ports 80 and 443 must be free on the server's computer and forwarded to it from your router. |
| Your domain, your proxy | assistant connect domain --host kelo.example.com --proxy | Fits a proxy you already run (Nginx Proxy Manager, Traefik, Caddy). Kelo prints the exact settings to enter. |
Put uv run in front of each command. To close it again: uv run assistant connect off.
Through Nginx Proxy Manager
If you already run Nginx Proxy Manager (NPM) and own a domain, this takes about five minutes. Replace kelo.example.com with your own name.
- In your DNS, point
kelo.example.comat the address your NPM answers on (the same record your other NPM hosts use). - On the computer where Kelo is installed, run
uv run assistant connect domain --host kelo.example.com --proxy. Kelo now listens on your home network and prints the address to forward to, likehttp://192.168.1.20:8080. - In NPM open Hosts → Proxy Hosts → Add Proxy Host. On Details: Domain Names
kelo.example.com, Schemehttp, Forward Hostname / IP the address Kelo printed (withouthttp://), Forward Port the port it printed (8080 unless you changed it). Turn on Websockets Support and Block Common Exploits. - On SSL: pick Request a new SSL Certificate, turn on Force SSL and HTTP/2 Support, accept the Let’s Encrypt terms.
- On Advanced, paste these two lines so replies stream as they are written and photos can be uploaded, then press Save:
proxy_buffering off; proxy_request_buffering off; proxy_cache off; proxy_read_timeout 300s; proxy_send_timeout 300s; client_max_body_size 0; - Check it with
uv run assistant connect status, then runuv run assistant phone addand scan the QR code with the Kelo app. The app now useshttps://kelo.example.com.
Kelo speaks plain http on your home network, so let only NPM reach that port if your firewall allows it. To undo it, run uv run assistant connect off and delete the host in NPM.
After installing
- Change how much it may use
uv run assistant limits --chooseoffers recommended, minimum, no limits, or your own numbers. - One for each family member
uv run assistant instance create NAMEstarts one more Kelo server on the same computer, with its own port, password, data and keys. - Check on it
docker compose ps, and the server's log withdocker compose logs server.
Stuck? uv run assistant --help, and --help on each command, list every option.