nanobot 쓰는 법

nanobot은 HKUDS가 만든 초경량 오픈소스 셀프호스트 개인 AI 에이전트다. Python으로 쓰여 있고, 브라우저 WebUI·터미널·채팅 앱에서 같은 런타임을 돌린다. 이 글은 “이게 왜 떴는지”가 아니라 받아서 켜는 법만 다룬다. 공식 README, nanobot.wiki, PyPI nanobot-ai 기준으로 적었다.

핵심 요약 (TL;DR)

• 패키지 이름: nanobot-ai · 확인한 최신: 0.3.5 · Python >=3.11 · 라이선스 MIT
• 안정 설치 중 하나만: curl 원커맨드 / uv tool install nanobot-ai / pip install nanobot-ai / 소스 editable
• 검증: nanobot --version
• 첫 실행 추천: nanobot webui → Settings → Models → 새 토픽에 Hello!
• 백그라운드: nanobot gateway --background (+ status / logs / restart / stop)
• 터미널: nanobot 또는 한 방 nanobot -m "Hello!"
• 저장소: HKUDS/nanobot (약 4.8만 스타) · 안정 문서: nanobot.wiki

할 수 있는 일

여기서 에이전트는 “한 번 답하고 끝나는 챗봇”이 아니라, 도구를 고르고 파일을 만지고 길게 이어서 일하는 런타임을 말한다. nanobot이 열어 둔 칸은 대략 이렇다.

• WebUI — 브라우저 워크벤치. 토픽·임시 채팅·도구 호출·디프·설정이 한곳에 있다. nanobot webui가 기본으로 http://127.0.0.1:8765를 연다.
• 터미널(TUI) — nanobot만 치면 네이티브 터미널 클라이언트가 뜬다. WebUI와 세션·로컬 게이트웨이를 공유한다.
• 게이트웨이(gateway) — WebUI·채팅 채널·자동화·하트비트가 붙는 긴 수명 프로세스. 터미널을 닫아도 돌리려면 nanobot gateway --background.
• MCP — Model Context Protocol. 외부 도구/서버를 에이전트에 붙이는 표준 쪽 인터페이스다. WebUI Apps에서 프리셋·커스텀 서버를 추가한다.
• 하네스 — 모델·도구·메모리·채널을 한 루프로 묶는 실행 뼈대. nanobot은 그 코어를 작게 유지한다고 README가 적는다.
• 파일·셸·웹 검색/페치·크론·이미지 생성·서브에이전트, Dream을 통한 장기 메모리, OpenAI 호환 API·Python SDK, Telegram/Discord/Slack 등 채팅 앱 연결.

필요한 것

VRAM·디스크 용량 숫자는 공식 설치 가이드에 고정값이 없다. 모델은 네가 고른 프로바이더 쪽 요구를 따른다. 여기서는 발명하지 않는다.

단계

1) 설치 — 안정 트랙 중 하나만

README 기준 안정(day-to-day)은 설치 스크립트·uv·pip다. 최신 실험은 소스 editable. 하나만 고른다.

A. 원커맨드 (macOS / Linux)

curl -fsSL https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.sh | sh

Windows PowerShell:

irm https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.ps1 | iex

기본은 PyPI에서 nanobot-ai를 깔고, 로컬 데스크톱이면 nanobot webui까지 이어 준다. 미리 보고만 하려면 --dry-run을 붙인다.

curl -fsSL https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.sh | sh -s -- --dry-run

B. uv

uv tool install nanobot-ai

C. pip

python -m pip install nanobot-ai

externally-managed-environment가 나오면 시스템 pip에 --break-system-packages를 쓰지 말고, 원커맨드·uv·pipx·venv로 간다. README가 그렇게 적는다.

D. 소스 editable

git clone https://github.com/HKUDS/nanobot.git
cd nanobot
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\Activate.ps1
python -m pip install -e .

소스 트랙은 Bun이 필요하다. 이후 명령은 안정 설치와 같다.

2) 검증

nanobot --version

nanobot이 PATH에 없으면 설치할 때 찍힌 전체 명령을 다시 쓰거나, uv tool run --from nanobot-ai nanobot --version, python -m nanobot --version처럼 같은 환경의 모듈 형태를 쓴다.

3) 첫 실행 — WebUI (추천)

nanobot webui

1. Settings → Models에서 프로바이더·자격증명·모델을 고른다.
2. 새 토픽을 열고 Hello!를 보낸다.
3. 프로젝트 작업 전에 컴포저에서 워크스페이스와 접근 모드를 확인한다.

정상 답장이 오면 프로바이더·모델·워크스페이스·브라우저 게이트웨이가 같이 돈 것이다. 첫 실행 WebUI는 localhost만 듣는다.

4) 백그라운드 게이트웨이

모델 설정을 WebUI로 끝낸 뒤, 터미널을 닫아도 채널·자동화를 유지하려면:

nanobot gateway --background

상태·로그·재시작·중지:

nanobot gateway status
nanobot gateway logs
nanobot gateway restart
nanobot gateway stop

포그라운드만 원하면 nanobot gateway. WebUI 자동 오픈 없이 같은 게이트웨이를 현재 터미널에 붙인다.

5) 터미널

nanobot

실행 디렉터리가 워크스페이스가 된다. /로 명령 목록, /sessions로 대화 전환, @로 앱·MCP·세션 멘션.

한 요청만:

nanobot -m "Hello!"

모델이 아직이면 먼저 nanobot webui → Settings → Models.

6) 로컬 모델 (선택)

README는 Ollama·vLLM 등 로컬 OpenAI 호환 서버를 프로바이더로 붙일 수 있다고 적는다. 이 가이드의 주 경로는 그 엔진을 설치·서빙하는 것이 아니라, nanobot 설치 → WebUI → Settings → Models다. 로컬 서버를 쓸 때는 providers.md와 Provider Cookbook을 본다. 막히면 아래 표의 “로컬 연결 거부” 행.

막히는 지점

공식 troubleshooting.md 요지. 먼저 CLI를 고치고, 그다음 게이트웨이·WebUI·채팅 앱 순이다.

nanobot --version
nanobot status
nanobot agent -m "Hello!"

이슈를 열 때는 설치 방법, nanobot --version, OS·Python, 실행한 명령, 살균한 nanobot status·설정을 붙인다. API 키·봇 토큰은 넣지 않는다.

마치며

nanobot 쓰는 법은 짧게 끝난다. nanobot-ai를 하나 고른 방식으로 깔고, nanobot --version으로 확인한 뒤, nanobot webui에서 Settings → Models로 모델을 붙이고 Hello를 보낸다. 계속 돌릴 거면 nanobot gateway --background, 터미널만 쓸 거면 nanobot 또는 nanobot -m "...".

더 깊은 설정·채널·배포는 nanobot.wiki와 저장소 docs/를 본다. 이 글은 설치부터 첫 Hello까지의 검색용 가이드다.

이 글은 AI가 작성하여 자동 발행된 콘텐츠입니다.