7. 10. 2026

Nanobot na vlastním serveru: instalace a ovládání přes Telegram

Nanobot je open-source (licence MIT) ultralehký framework pro osobního AI agenta napsaný v Pythonu. Provozujete ho sami na vlastním stroji a používat ho můžete ve WebUI, v terminálu nebo v chatovacích aplikacích. Agent umí pracovat s nástroji (shell, soubory, web), má paměť a plánované úlohy. Konfigurace, historie i klíče zůstávají u vás, ne u cizí služby.

Tento návod ukazuje, jak nanobot nasadit na Linuxový server v Dockeru a ovládat ho přes vlastního Telegram bota, od instalace po první odpověď. Jako model použijeme Claude přes Anthropic API, nanobot ale podporuje i další poskytovatele.

Co budete potřebovat

Linuxový server (stačí malý VPS) s Dockerem a pluginem docker compose
API klíč poskytovatele modelu (zde Anthropic)
Telegram účet

V příkazech níže nahraďte hodnoty v lomených závorkách svými: <ANTHROPIC_API_KEY>, <BOT_TOKEN>, <TELEGRAM_USER_ID>. Tajné údaje nikdy necommitujte do repozitáře.

1. Instalace

git clone https://github.com/HKUDS/nanobot.git
cd nanobot
docker compose up -d nanobot-gateway

První build image trvá zhruba 5 minut. Spouštíme jen službu nanobot-gateway, kontejner nanobot-api pro tento scénář nepotřebujete.

Pokud narazíte na chyby Dockeru na headless serveru:

# "unknown shorthand flag: 'd'" / permission denied u pluginu compose
chmod +x ~/.docker/cli-plugins/docker-compose

# build padá na credential helperu (chybí secrets service)
echo '{}' > ~/.docker/config.json

Pokud build po tom dál padá na přihlašovacích údajích, stáhněte základní image ručně (názvy jsou na řádcích FROM v Dockerfile):

docker pull node:24-bookworm-slim
docker pull ghcr.io/astral-sh/uv:python3.12-bookworm-slim

2. Onboarding: provider a model

Kontejner běží jako uživatel s UID 1000, proto musí být konfigurační adresář na hostu vlastněný stejným UID. Průvodce se spouští s --user nanobot, jinak skončí chybou Permission denied.

chown -R 1000:1000 ~/.nanobot/
docker compose exec --user nanobot nanobot-gateway nanobot onboard --wizard

V průvodci zadáte API klíč (<ANTHROPIC_API_KEY>) a model, například claude-sonnet-5. Klíč v Anthropic Console vytvářejte uvnitř konkrétního Workspace. Klíč na úrovni celé organizace skončí chybou, že není vázaný na workspace.

Konfigurace je v ~/.nanobot/config.json, pracovní soubory agenta v ~/.nanobot/workspace/.

3. Vytvoření bota v Telegramu

Otevřete v Telegramu @BotFather.
Pošlete příkaz /newbot.
Zadejte zobrazované jméno (libovolné) a uživatelské jméno, které musí končit na bot, například muj_server_bot.
BotFather vrátí token (<BOT_TOKEN>). Je to heslo k botovi, uložte ho do správce hesel.
Zjistěte své číselné Telegram ID (<TELEGRAM_USER_ID>), třeba zprávou pro @userinfobot.

Proč Telegram a ne WhatsApp: Telegram bot má vlastní identitu. WhatsApp kanál se naopak připojuje jako další zařízení k vašemu osobnímu číslu a každému, kdo vám napíše, může nabídnout párovací kód. Pro agenta s přístupem k serveru je to nevhodné.

4. Napojení Telegramu v nanobotu

Zapněte plugin kanálu:

docker compose exec --user nanobot nanobot-gateway nanobot plugins enable telegram

Do ~/.nanobot/config.json přidejte sekci kanálu:

{
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "<BOT_TOKEN>",
      "allowFrom": ["<TELEGRAM_USER_ID>"]
    }
  }
}

Pozor na formát: allowFrom je pole řetězců, tedy ["12345"]. Zápis [12345] ani "12345" neprojde validací a kanál se nespustí. Bez allowFrom běží kanál v režimu párování přes kód, hodnota ["*"] pustí dovnitř kohokoli, a tu u bota s přístupem k serveru nepoužívejte.

Po každé změně configu restartujte gateway a sledujte logy:

docker compose restart nanobot-gateway
docker compose logs -f nanobot-gateway

5. První test

Napište svému botovi v Telegramu zprávu, například „Kolik je volného místa na disku?“. Pokud odpoví, máte hotovo. Když mlčí, v logu najdete chybu validace configu nebo tokenu.

6. Bezpečnost: pravidla pro agenta

Nejdůležitější pojistkou je allowFrom s vaším ID. Druhou vrstvou jsou pravidla v ~/.nanobot/workspace/AGENTS.md, například:

## Pravidla pro správu serveru

### Vždy povoleno
- čtení souborů, `docker ps`, `docker logs`, `df -h`, diagnostika

### Vyžaduje potvrzení uživatele
- restart containeru, `git commit` / `git push`, úpravy souborů

### Nikdy bez výslovného zadání (a i pak se zeptej)
- `rm`, `docker rm`, `docker system prune`, databázové migrace

Je to instrukce pro model, ne technický limit. Agent ji dodržuje, dokud ji dodržuje.

7. Volitelně: správa serveru a repozitářů

Chcete-li, aby agent viděl repozitáře a ovládal Docker na hostu, přidejte do docker-compose.yml (sekce x-common-config, volumes):

volumes:
  - ~/.nanobot:/home/nanobot/.nanobot
  - /var/www:/var/www
  - /var/run/docker.sock:/var/run/docker.sock

Kontejner potřebuje i samotnou binárku docker. V Dockerfile přidejte docker.io do apt-get install a uživatele zařaďte do skupiny odpovídající socketu (GID zjistíte přes stat -c %g /var/run/docker.sock):

RUN groupadd -g 999 dockerhost || true && \
    useradd -m -u 1000 -s /bin/bash -G dockerhost nanobot

Změna volumes se projeví až po docker compose down && docker compose up -d, samotný restart nestačí. Po úpravě Dockerfile navíc spusťte docker compose build.

Riziko: přístup k Docker socketu je prakticky root na hostu. Agent může spustit nový kontejner s libovolným mountem a přečíst cokoli, včetně SSH klíčů. Pravidla z AGENTS.md tomu technicky nezabrání. Pro git push proto použijte dedikovaný deploy klíč s právem jen na potřebná repa a zvažte socket proxy, která povolí jen vybrané příkazy.

Shrnutí

Nanobot si za pár minut postavíte na vlastním serveru, přes BotFather mu vytvoříte Telegram identitu a allowFrom zajistí, že poslouchá jen vás. Čím víc oprávnění agentovi dáte, tím víc záleží na jeho pravidlech i na tom, kam míří vaše klíče. Začněte s read-only diagnostikou a oprávnění přidávejte postupně.

Odkazy: repozitář nanobotu · dokumentace konfigurace · nanobot.wiki