Installation steps
-
Install Docker
On Mac, install Docker Desktop. On Linux, the command below can install Docker for you. On Windows you do not need Docker for the Windows line in the next step.
On Mac, open Docker Desktop once and leave it running before the second step.
-
One command
Paste this into a terminal (PowerShell on Windows).
curl -fsSL https://kelo.chat/install.sh | bashirm https://kelo.chat/install-windows.ps1 | iexOn Mac and Linux, the command checks Docker, installs git and uv if they are missing, downloads the official Kelo server and checks its signature, asks how much it may use, starts it, asks for a kelo.chat address (offered for now) and shows a QR code for your phone. Running it again updates Kelo; your data is kept.
On Windows the line does not need Docker. Windows asks for administrator permission once (click Yes), installs Kelo Server, and opens the setup page in your browser. Nothing else is asked in the terminal. If you want Docker Desktop on Windows instead, use
irm https://kelo.chat/install.ps1 | iex. -
Scan the QR code with the app
Install the Kelo app on your phone from the download section and pick the one for your phone. Open it and scan the QR code the command showed. Then choose the AI model and enter its key in the app.
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.
The installer takes care of git and uv (the Python tool that runs Kelo's setup). The AI key goes into the app.
Install by hand (with commands)
To do the steps yourself, follow these in order. Run every command in a terminal, inside the Kelo folder you downloaded. Install and start Docker first (the first step above).
-
Download the Kelo server
git clone https://github.com/kelo-chat/kelo-server kelo cd keloA public repository with the server part of Kelo only.
-
Set up and start
uv run assistant setup --from-releasePulls the official images and checks their signatures, asks a few questions, then starts the server. By default the server only listens inside the computer it runs on (127.0.0.1:8080). Without
--from-releaseit builds the images on this computer instead; that is slower.- 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. -
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 last step of the setup lets you pick an address and shows the QR code right away. If you skipped it, use the commands below. The easiest way is a kelo.chat subdomain, 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.
Other 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.