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. Set reasoning = true only for models that support thinking, since it is what makes thinkingLevel apply on a custom endpoint.

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. Stavrobot picks the provider's headless login method, so you never get redirected to an unreachable localhost callback. With Anthropic, after you select Authorize, Anthropic shows a code, which you copy and paste into the Stavrobot login page. Providers with a device-code flow show the code on the Stavrobot page instead, and you type it on the provider's site. 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). By default it uses Claude Code with subscription auth (OAuth), separate from the main app's API key. To use an Anthropic-compatible API endpoint instead, set both [coder].apiKey and [coder].baseUrl in config.toml; Claude Code then uses them as ANTHROPIC_API_KEY and ANTHROPIC_BASE_URL. The top-level apiKey/baseUrl only configure the main app's model and never affect the coder. Setting only one of the two [coder] keys is a startup error.

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 (skip this and the next step if you set [coder].apiKey/[coder].baseUrl): 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.