준비물과 사양
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 폴더 안에서 실행해요.
-
Kelo 내려받기
git clone https://github.com/kelo-chat/kelo-server kelo cd kelo -
처음 설정
uv run assistant setup몇 가지를 물어봐요.
- 비서의 브라우저 — Chromium(기본, 오픈 소스) 또는 Google Chrome.
- 서버가 얼마나 쓸지 — 권장, 최소, 제한 없음.
그 밖에 묻는 항목은 기본값 그대로 두면 돼요.
설정은 폴더 안의
.env파일에 저장돼요. 여기에 서버 접속 비밀번호(ASSISTANT_TOKEN)와 저장한 키를 잠그는 열쇠(ASSISTANT_SECRET_KEY)가 새로 만들어져요. 이 파일은 남에게 보여 주지 말고, 열쇠를 잃으면 앱에 넣은 키를 다시 넣어야 하니 따로 백업해 두세요. -
서버 켜기
docker compose up -d --build처음에는 이미지를 만드느라 몇 분 걸려요. 서버는 기본적으로 서버를 설치한 컴퓨터 안(127.0.0.1:8080)에서만 열려요.
-
AI 모델 키 넣기
쓸 AI 모델의 API 키는 앱의 설정에서 넣으면 돼요.
.env에 직접 적어도 돼요(예:OPENROUTER_API_KEY=…). -
밖에서도 닿게 하기
가장 쉬운 건 현재 한정 제공 중인
kelo.chat하위 주소예요. 제공 범위와 조건은 바뀔 수 있어요.uv run assistant connect kelo --name 원하는이름 uv run assistant connect statusstatus는 주소와 함께, 그 주소로 실제로 서버에 닿는지 확인해 줘요. 다른 방법은 아래 표를 보세요. -
휴대폰 연결
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 포트만 되고, 베타라 대역폭 제한이 있어요. |
| 내 도메인 + Cloudflare | assistant 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은 내 이름으로 바꿔 주세요.
- DNS에서
kelo.example.com이 NPM이 받는 주소를 가리키게 해요 (다른 NPM 호스트와 같은 설정이에요). - Kelo가 설치된 컴퓨터에서
uv run assistant connect domain --host kelo.example.com --proxy를 실행해요. Kelo가 집 네트워크에서 요청을 받기 시작하고, 넘겨 줄 주소를http://192.168.1.20:8080처럼 출력해 줘요. - 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를 켜요. - SSL 탭: Request a new SSL Certificate를 고르고 Force SSL과 HTTP/2 Support를 켠 뒤 Let’s Encrypt 약관에 동의해요.
- 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; 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에 옵션이 모두 나와 있어요.