/installInstall the server

Set up the Kelo server.
Run it yourself.

The Kelo server runs in Docker. Follow these steps and you'll finish with your phone connected.

Opens soon
curl -fsSL https://kelo.chat/install.sh | bash
irm https://kelo.chat/install.ps1 | iex

The one-line install opens the day Kelo goes public. Until then, follow the steps below.

What you need

Minimum

2 GB RAM · 2 CPU cores · 10 GB free disk

Recommended

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.

  1. Download Kelo

    git clone https://github.com/kelo-chat/kelo-server kelo
    cd kelo
  2. First-time setup

    uv run assistant setup

    It 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 .env file 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.

  3. Start the server

    docker compose up -d --build

    The first build takes a few minutes. By default the server only listens inside the computer it runs on (127.0.0.1:8080).

  4. 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 example OPENROUTER_API_KEY=…).

  5. Make it reachable from outside

    The easiest way is a <name>.kelo.chat address, offered for now. Availability and terms may change.

    uv run assistant connect kelo --name yourname
    uv run assistant connect status

    status shows the address and checks that it really reaches your server. For other ways, see the table below.

  6. Connect your phone

    uv run assistant phone add

    A 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.

WayCommandKeep in mind
Kelo address (offered for now)assistant connect kelo --name NAMEEasiest: no router changes. Traffic uses https through a Cloudflare Tunnel.
Tailscale (private)assistant connect tailscaleMost private: nothing is public. Every phone needs the Tailscale app on the same account.
Tailscale Funnel (public)assistant connect funnelPublic 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 Cloudflareassistant connect cloudflare --domain example.comUses a domain on your own Cloudflare account. Needs cloudflared on the computer the server runs on.
Your domain, directassistant connect domain --host me.example.com --directNothing in between. Ports 80 and 443 must be free on the server's computer and forwarded to it from your router.
Your domain, your proxyassistant connect domain --host kelo.example.com --proxyFits 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.

  1. In your DNS, point kelo.example.com at the address your NPM answers on (the same record your other NPM hosts use).
  2. 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, like http://192.168.1.20:8080.
  3. In NPM open Hosts → Proxy Hosts → Add Proxy Host. On Details: Domain Names kelo.example.com, Scheme http, Forward Hostname / IP the address Kelo printed (without http://), Forward Port the port it printed (8080 unless you changed it). Turn on Websockets Support and Block Common Exploits.
  4. On SSL: pick Request a new SSL Certificate, turn on Force SSL and HTTP/2 Support, accept the Let’s Encrypt terms.
  5. 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;
  6. Check it with uv run assistant connect status, then run uv run assistant phone add and scan the QR code with the Kelo app. The app now uses https://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 --choose offers recommended, minimum, no limits, or your own numbers.
  • One for each family member uv run assistant instance create NAME starts 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 with docker compose logs server.

Stuck? uv run assistant --help, and --help on each command, list every option.

Start your own AI assistant

Free and open source under AGPL-3.0. Any machine that runs Docker will do.