/install서버 설치하기

Kelo 서버,
직접 띄워 봐요.

Kelo 서버는 Docker로 돌아가요. 아래 순서대로 하면 휴대폰 연결까지 마칠 수 있어요.

곧 열려요
curl -fsSL https://kelo.chat/install.sh | bash
irm https://kelo.chat/install.ps1 | iex

한 줄 설치는 Kelo가 공개되는 날 열려요. 지금은 아래 순서대로 하면 돼요.

준비물과 사양

최소

RAM 2GB · CPU 2코어 · 남은 디스크 10GB

권장

RAM 4GB · CPU 4코어 · 남은 디스크 20GB

서버가 얼마나 쓸지는 설치할 때 권장, 최소, 제한 없음 중에서 고르고, 나중에 바꿀 수 있어요.

  • Docker (Compose 포함). Mac·Windows는 Docker Desktop, Linux는 Docker Engine.
  • git Kelo를 내려받을 때 써요.
  • uv Kelo의 설정 명령 assistant를 실행하는 Python 도구예요. 필요한 Python은 uv가 알아서 받아요.
  • API 키 쓸 AI 모델의 키.

설치 순서

명령은 모두 터미널에서, 내려받은 Kelo 폴더 안에서 실행해요.

  1. Kelo 내려받기

    git clone https://github.com/kelo-chat/kelo-server kelo
    cd kelo
  2. 처음 설정

    uv run assistant setup

    몇 가지를 물어봐요.

    • 비서의 브라우저 — Chromium(기본, 오픈 소스) 또는 Google Chrome.
    • 서버가 얼마나 쓸지 — 권장, 최소, 제한 없음.

    그 밖에 묻는 항목은 기본값 그대로 두면 돼요.

    설정은 폴더 안의 .env 파일에 저장돼요. 여기에 서버 접속 비밀번호(ASSISTANT_TOKEN)와 저장한 키를 잠그는 열쇠(ASSISTANT_SECRET_KEY)가 새로 만들어져요. 이 파일은 남에게 보여 주지 말고, 열쇠를 잃으면 앱에 넣은 키를 다시 넣어야 하니 따로 백업해 두세요.

  3. 서버 켜기

    docker compose up -d --build

    처음에는 이미지를 만드느라 몇 분 걸려요. 서버는 기본적으로 서버를 설치한 컴퓨터 안(127.0.0.1:8080)에서만 열려요.

  4. AI 모델 키 넣기

    쓸 AI 모델의 API 키는 앱의 설정에서 넣으면 돼요. .env에 직접 적어도 돼요(예: OPENROUTER_API_KEY=…).

  5. 밖에서도 닿게 하기

    가장 쉬운 건 현재 한정 제공 중인 kelo.chat 하위 주소예요. 제공 범위와 조건은 바뀔 수 있어요.

    uv run assistant connect kelo --name 원하는이름
    uv run assistant connect status

    status는 주소와 함께, 그 주소로 실제로 서버에 닿는지 확인해 줘요. 다른 방법은 아래 표를 보세요.

  6. 휴대폰 연결

    uv run assistant phone add

    터미널에 QR 코드가 떠요. Kelo 앱의 연결 화면에서 스캔하면 끝이에요. 링크는 10분 동안 한 번만 쓸 수 있고, 휴대폰을 더 연결하려면 다시 실행하면 돼요.

밖에서 연결하는 방법

한 번에 하나만 쓰고, 새 방법을 고르면 이전 방법은 자동으로 꺼져요.

방법명령알아 둘 점
Kelo 주소 (현재 한정 제공)assistant connect kelo --name 이름가장 쉬워요. 공유기 설정이 없어요. https로 Cloudflare 터널을 통해 연결돼요.
Tailscale (나만)assistant connect tailscale가장 사적이에요. 밖으로 공개되는 게 없어요. 휴대폰마다 같은 계정의 Tailscale 앱이 필요해요.
Tailscale Funnel (공개)assistant connect funnel도메인 없이 공개 https, 서버까지 암호화돼요. 443·8443·10000 포트만 되고, 베타라 대역폭 제한이 있어요.
내 도메인 + Cloudflareassistant connect cloudflare --domain example.com내 Cloudflare 계정의 도메인을 써요. 서버를 설치한 컴퓨터에 cloudflared가 필요해요.
내 도메인, 직접assistant connect domain --host me.example.com --direct중간에 아무도 없어요. 80·443 포트가 비어 있고 공유기에서 서버를 설치한 컴퓨터로 넘겨줘야 해요.
내 도메인, 내 프록시assistant connect domain --host kelo.example.com --proxy이미 쓰는 Nginx Proxy Manager, Traefik, Caddy에 맞춰요. 넣을 설정을 Kelo가 출력해 줘요.

모든 명령 앞에는 uv run을 붙여요. 연결을 닫을 때는 uv run assistant connect off.

Nginx Proxy Manager로 연결하기

이미 Nginx Proxy Manager(NPM)를 쓰고 가진 도메인이 있다면 5분 정도면 돼요. kelo.example.com은 내 이름으로 바꿔 주세요.

  1. DNS에서 kelo.example.com이 NPM이 받는 주소를 가리키게 해요 (다른 NPM 호스트와 같은 설정이에요).
  2. Kelo가 설치된 컴퓨터에서 uv run assistant connect domain --host kelo.example.com --proxy를 실행해요. Kelo가 집 네트워크에서 요청을 받기 시작하고, 넘겨 줄 주소를 http://192.168.1.20:8080처럼 출력해 줘요.
  3. NPM에서 Hosts → Proxy Hosts → Add Proxy Host를 열어요. Details 탭: Domain Names에 kelo.example.com, Scheme은 http, Forward Hostname / IP에는 Kelo가 출력한 주소(http://는 빼고), Forward Port에는 출력된 포트(바꾸지 않았다면 8080)를 넣어요. Websockets Support와 Block Common Exploits를 켜요.
  4. SSL 탭: Request a new SSL Certificate를 고르고 Force SSL과 HTTP/2 Support를 켠 뒤 Let’s Encrypt 약관에 동의해요.
  5. Advanced 탭에 아래 두 줄을 붙여 넣어요. 답이 써지는 대로 바로 보이고 사진도 올릴 수 있게 해 줘요. 그다음 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. uv run assistant connect status로 확인한 뒤 uv run assistant phone add를 실행하고 Kelo 앱으로 QR 코드를 스캔해요. 이제 앱은 https://kelo.example.com을 써요.

Kelo는 집 네트워크 안에서 평문 http로 답해요. 방화벽이 허용하면 NPM만 그 포트에 닿게 해 주세요. 되돌리려면 uv run assistant connect off를 실행하고 NPM에서 그 호스트를 지워요.

설치 후에

  • 사용량 바꾸기 uv run assistant limits --choose로 권장·최소·제한 없음·직접 정하기 중에서 골라요.
  • 가족도 따로 uv run assistant instance create 이름은 같은 컴퓨터에 Kelo 서버를 하나 더 띄워요. 포트, 접속 비밀번호, 데이터, 키가 모두 따로예요.
  • 상태 보기 docker compose ps, 서버 기록은 docker compose logs server.

막히는 부분이 있으면 uv run assistant --help와 각 명령의 --help에 옵션이 모두 나와 있어요.

내 서버에서 일하는 AI 비서를 시작하세요

무료 오픈 소스(AGPL-3.0)예요. Docker가 돌아가는 컴퓨터면 설치할 수 있어요.