/install서버 설치하기

Kelo 서버,
직접 띄워 봐요.

Kelo 서버는 Docker 위에서 돌아가요. 세 단계, 5분 정도면 휴대폰까지 연결돼요.

설치 순서

  1. Docker 설치

    Mac은 Docker Desktop을 설치해요. Linux는 아래 명령이 Docker를 직접 설치할 수 있어요. Windows는 다음 단계의 Windows 줄에 Docker가 필요하지 않아요.

    Mac에서는 Docker Desktop을 한 번 열어서 실행 중인 상태로 두세요. 두 번째 단계 전에 실행돼 있어야 해요.

  2. 한 줄 명령

    터미널(Windows는 PowerShell)에 아래 명령을 붙여 넣어요.

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

    Mac과 Linux에서 명령은 Docker를 확인하고, 없는 도구(git, uv)를 설치한 뒤, 공식 Kelo 서버를 내려받아 서명을 확인해요. 서버가 얼마나 쓸지 고르게 하고, 서버를 켠 다음, kelo.chat 하위 주소(현재 한정 제공)를 정하면 휴대폰을 연결할 QR 코드를 보여 줘요. 다시 실행하면 Kelo가 업데이트되고, 데이터는 그대로 남아요.

    Windows는 Docker가 필요 없어요. 이 줄은 관리자 권한을 한 번만 물어보고(예를 누르세요), Kelo 서버를 설치한 다음 설정 페이지를 브라우저에서 열어 줘요. 터미널에서 더 묻는 것은 없어요. Docker Desktop을 쓰고 싶다면 irm https://kelo.chat/install.ps1 | iex를 실행하세요.

  3. 앱으로 QR 스캔

    휴대폰에 Kelo 앱을 설치하세요. 앱 내려받기에서 휴대폰에 맞는 앱을 고르면 돼요. 앱을 열고 명령이 보여 준 QR 코드를 스캔하면 서버에 연결돼요. 그다음 앱에서 쓸 AI 모델과 키를 넣으세요.

준비물과 사양

최소

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

권장

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

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

  • Docker (Compose 포함). Mac·Windows는 Docker Desktop, Linux는 Docker Engine.

git과 uv(Kelo의 설정을 실행하는 Python 도구)는 설치 명령이 알아서 설치하고 써요. AI 모델의 키는 앱에서 넣어요.

직접 설치하기 (명령어로)

설치 명령 대신 직접 하려면 아래 순서대로 해요. 명령은 모두 터미널에서, 내려받은 Kelo 폴더 안에서 실행해요. Docker는 위의 첫 단계대로 먼저 설치하고 실행해 두세요.

  1. Kelo 서버 내려받기

    git clone https://github.com/kelo-chat/kelo-server kelo
    cd kelo

    Kelo 서버 부분만 담은 공개 저장소예요.

  2. 설정하고 시작하기

    uv run assistant setup --from-release

    공식 이미지를 내려받고 서명을 확인한 뒤, 몇 가지를 물어보고 서버를 켜요. 서버는 기본적으로 서버를 설치한 컴퓨터 안(127.0.0.1:8080)에서만 열려요. --from-release를 빼면 이미지를 이 컴퓨터에서 직접 빌드해요(느려요).

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

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

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

  3. AI 모델 키 넣기

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

  4. 밖에서도 닿게 하기

    설정의 마지막 단계에서 주소를 정하고 QR 코드까지 바로 받을 수 있어요. 그때 건너뛰었다면 아래 명령으로 해요. 가장 쉬운 건 현재 한정 제공 중인 kelo.chat 하위 주소예요. 제공 범위와 조건은 바뀔 수 있어요.

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

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

  5. 휴대폰 연결

    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가 돌아가는 컴퓨터면 설치할 수 있어요.