Stavrobot

Stavrobot is a personal AI assistant built with the principle of "all the access an AI assistant needs, and no more".

It has all the nice features of an AI assistant, but focuses on sandboxing, isolation, and minimal permissions. It's lightweight and is deployed with only a docker compose up.

Features

• Secure. Everything runs in a container, your host OS is completely invisible to the AI. The AI doesn't see any secrets unless you want it to.
• Light. Doesn't run one container per component. Plugins all run in a single container, separated by Unix permissions.
• Use any model you want. Local, OpenRouter, Anthropic/OpenAI. Whatever Pi supports, the bot can use.
• Signal/Telegram/WhatsApp/Email integration. Two-way messaging, with formatting, attachments, etc.
• Pebble Index integration. Ring recordings can be queued directly for the agent.
• Three-tier knowledge. Remembers everything without blowing out its context. Intelligently and transparently retrieves data from its memory.
• Low token usage. Various optimizations have been made to be light on token usage. It even uses TOON internally.
• Plugins. Install plugins and extend Stavrobot's capabilities by just giving it a git repo URL. Plugins are isolated from each other — each runs as a dedicated system user with no access to other plugins' files or configuration.
• Subagents. The main agent can create subagents with their own conversation context, system prompt, and restricted tool access. Useful for talking to outside people to complete tasks or arrange things, while having a buffer between the outside person and the main agent.
• Self-programming. The agent can program and extend itself.
• Sandboxed Python execution. Arbitrary Python with pip dependencies via uv, isolated from the host environment.
• Scheduling. The agent can schedule its own recurring or one-shot tasks.

Quickstart

AI-assisted install: Tell your coding AI (Claude Code, Cursor, Windsurf, etc.) to fetch and follow https://stavrobot.stavros.io/INSTALL.md — it will walk you through the whole setup interactively.

Manual install:

1. Message @BotFather on Telegram to create a bot and copy the token. Message @userinfobot to get your Telegram user ID (this is used as the chat ID).

2. Copy env.example to .env and change POSTGRES_PASSWORD to something secure and TZ to your timezone.

3. Copy config.example.toml to data/main/config.toml and fill in the required fields: apiKey, password, publicHostname, [owner].name, [owner].telegram (your chat ID), and [telegram].botToken. Everything else in the file is optional.

4. docker compose up --build

That's it. Message your bot on Telegram and it will respond. See the detailed setup sections below for Signal, WhatsApp, email, and other options.

Setup

Config

1. Copy config.example.toml to data/main/config.toml.
2. Fill in API keys and settings. The example file has comments explaining each section.
3. At minimum, set authFile (or apiKey) and publicHostname. Everything else is optional.
4. Copy env.example to .env and set your timezone (TZ). Postgres credentials and other environment settings can also be overridden there. Always set POSTGRES_PASSWORD to something secure — the default is a weak placeholder and should not be used in production.

Config editor

After the app starts, open /settings/config to edit config.toml in the browser. The page is protected by HTTP Basic Auth and displays the raw configuration, including any secrets it contains. A valid save creates a single <CONFIG_PATH>.bak backup, saves the new content, and restarts the app; this interrupts any in-progress agent turn.

plugin-runner, coder, signal-bridge, and python-runner read config.toml only when they start. Changes that affect them, such as the password, require manually restarting those containers.

Custom and OpenAI-compatible endpoints

Stavrobot can be pointed at any OpenAI-compatible endpoint (Ollama, LiteLLM, vLLM, etc.) or a custom Anthropic-compatible proxy by setting baseUrl in config.toml. See config.example.toml for the required fields and example configurations.

Authentication

The app supports two authentication modes: API key or OAuth.

• API key: Set apiKey in config.toml. No login or logout needed.
• OAuth: Set authFile in config.toml (a path where credentials will be stored). The login page works with any OAuth provider supported by Pi.
  • Login: Visit <your-hostname>/login in a browser. Follow the prompts on the page, and credentials are saved to the auth file. If auth expires while the bot is running, it sends a message with the login URL to you via your messaging platform.
  • Logout: Delete the file at the authFile path. The bot will detect missing credentials on the next message and prompt you to log in again.

Claude Code setup

The coder container is optional (needed only for the self-programming feature). It uses Claude Code with subscription auth (OAuth), separate from the main app's API key.

Docker Compose profiles are comma-separated, so you can combine them (e.g. COMPOSE_PROFILES=signal,coder).

1. Set COMPOSE_PROFILES in your .env file to include coder (e.g. COMPOSE_PROFILES=coder, or COMPOSE_PROFILES=signal,coder if you are also using Signal).
2. Start the containers: docker compose --profile coder up --build
3. Log in: docker compose exec -u coder coder claude (it will prompt you to log in if you haven't).
4. Follow the browser-based OAuth flow.
5. Set [coder].model in your config to a Claude Code model alias (sonnet, opus, or haiku).

Signal setup

Signal requires a separate phone number — not your personal one. A prepaid SIM or VoIP number works.

1. Uncomment COMPOSE_PROFILES=signal in your .env file to enable the signal-bridge container.
2. Build the containers: docker compose --profile signal build
3. Register Signal on the container (pick one):
   • Link to an existing Signal account: docker compose --profile signal run --rm --entrypoint bash signal-bridge -c 'signal-cli link -n "Stavrobot" | tee >(xargs -L 1 qrencode -t utf8)' — scan the QR code with your phone (Signal > Settings > Linked devices).
   • Register a new number: docker compose --profile signal run --rm --entrypoint bash signal-bridge -c 'signal-cli -u +YOUR_NUMBER register', then verify with docker compose --profile signal run --rm --entrypoint bash signal-bridge -c 'signal-cli -u +YOUR_NUMBER verify CODE'.
4. Set [signal].account in your config.
5. Start the containers: docker compose up --build
6. After first startup, add allowed numbers via the /settings web UI.
7. Important: signal-cli does not resolve phone numbers for contacts it hasn't messaged yet. The bot must send the first message to each contact by phone number before it can receive and identify incoming messages from them. To trigger this for the owner, run:

   docker compose exec app node -e "fetch('http://localhost:3001/chat',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({message:'Send the message \"Hello from Stavrobot\" to my Signal number.'})}).then(r=>r.text()).then(console.log)"
   

8. See the signal-cli quickstart for details.

Telegram setup