picobot

Picobot

The AI agent that runs anywhere — even on a $5 VPS.

Love the idea of open-source AI agents like OpenClaw but tired of the bloat? Picobot gives you the same power — persistent memory, tool calling, skills, Telegram and Discord integration — in a single ~9MB binary that boots in milliseconds.

No Python. No Node. No 500MB container. Just one Go binary and a config file.

Why Picobot?

Picobot runs happily on a $5/mo VPS, a Raspberry Pi, or even an old Android phone via Termux.

Quick Start — 30 seconds

Docker Run

docker run -d --name picobot \
  -e OPENAI_API_KEY="your-key" \
  -e OPENAI_API_BASE="https://openrouter.ai/api/v1" \
  -e PICOBOT_MODEL="openrouter/free" \
  -e PICOBOT_MAX_TOKENS=8192 \
  -e PICOBOT_MAX_TOOL_ITERATIONS=100 \
  -e TELEGRAM_BOT_TOKEN="your-telegram-token" \
  -v ./picobot-data:/home/picobot/.picobot \
  --restart unless-stopped \
  louisho5/picobot:latest

All config, memory, and skills are persisted in ./picobot-data on your host.

Docker Compose

Create a docker-compose.yml:

services:
  picobot:
    image: louisho5/picobot:latest
    container_name: picobot
    restart: unless-stopped
    environment:
      - OPENAI_API_KEY=your-key
      - OPENAI_API_BASE=https://openrouter.ai/api/v1
      - PICOBOT_MODEL=openrouter/free
      - PICOBOT_MAX_TOKENS=8192
      - PICOBOT_MAX_TOOL_ITERATIONS=100
      - TELEGRAM_BOT_TOKEN=your-telegram-token
      - TELEGRAM_ALLOW_FROM=your-user-id
    volumes:
      - ./picobot-data:/home/picobot/.picobot

Then run:

docker compose up -d

From Source

go build -o picobot ./cmd/picobot
./picobot onboard                     # creates ~/.picobot config + workspace
./picobot agent -m "Hello!"           # single-shot query
./picobot channels login              # login to channels (Telegram, Discord, Slack, WhatsApp)
./picobot gateway                     # long-running mode with Telegram

Architecture

Actually the logic is simple and straightforward. Messages flow through a Chat Hub (inbound/outbound channels) into the Agent Loop, which builds context from memory/sessions/skills, calls the LLM via OpenAI-compatible API, and executes tools (filesystem, exec, web, etc.) before sending replies back through the hub.

Notes: Channel refers to communication channels (e.g., Telegram, Discord, Slack, WhatsApp, etc.).

Features

16 Built-in Tools + MCP Extensions

The agent can take real actions — not just chat:

MCP Servers: extend the agent with any MCP-compliant server — npx, uvx, a plain binary, docker run, or an HTTP endpoint. Tools are registered automatically as mcp_{server}_{tool} at startup. See CONFIG.md.

Persistent Memory

Picobot remembers things between conversations:

• Daily notes — auto-organized by date
• Long-term memory — survives restarts
• Ranked recall — retrieves the most relevant memories for each query

picobot memory recent --days 7     # what happened this week?
picobot memory rank -q "meeting"   # find relevant memories

Skills System

Teach your agent new tricks. Skills are modular knowledge packages that extend the agent:

You: "Create a skill for checking weather using curl wttr.in"
Agent: Created skill "weather" — I'll use it from now on.

Skills are just markdown files in ~/.picobot/workspace/skills/. Create them via the agent or manually.

Telegram Integration

Chat with your agent from your phone. Set up in 2 minutes:

1. Message @BotFather — /newbot — copy the token
2. Add the token to config or pass as TELEGRAM_BOT_TOKEN env var
3. Start the communication gateway

See HOW_TO_START.md for a detailed BotFather walkthrough.

Discord Integration

Connect your agent to Discord servers:

1. Go to Discord Developer Portal
2. Create a new application and bot
3. Enable Message Content Intent in Bot settings
4. Copy the bot token
5. Add to config under channels.discord in your config.json

The bot will respond when mentioned in servers, or to all messages in DMs.

See HOW_TO_START.md for a detailed Discord Bot walkthrough.

Slack Integration

Connect your agent to Slack via Socket Mode:

1. Go to Slack API Apps and create an app
2. Enable Socket Mode and generate an App-Level Token (xapp-...)
3. Add Bot Token scopes: app_mentions:read, chat:write, channels:history, groups:history, im:history, mpim:history, files:read
4. Enable Event Subscriptions and subscribe to: app_mention, message.im
5. Install the app to your workspace and copy the Bot Token (xoxb-...)
6. Add to config under channels.slack in your config.json

The bot responds when mentioned in channels, and responds to all DMs from allowed users (DMs ignore the channel allowlist).

Heartbeat

A configurable periodic check (default: 60s) that reads HEARTBEAT.md for scheduled tasks — like a personal cron with natural language.

Configuration

Picobot uses a single JSON config at ~/.picobot/config.json:

{
  "agents": {
    "defaults": {
      "model": "google/gemini-2.5-flash",
      "maxTokens": 8192,
      "temperature": 0.7,
      "maxToolIterations": 200
    }
  },
  "providers": {
    "openai": {
      "apiKey": "sk-or-v1-YOUR_KEY",
      "apiBase": "https://openrouter.ai/api/v1"
    }
  },
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "YOUR_TELEGRAM_BOT_TOKEN",
      "allowFrom": ["YOUR_TELEGRAM_USER_ID"]
    },
    "discord": {
      "enabled": true,
      "token": "YOUR_DISCORD_BOT_TOKEN",
      "allowFrom": ["YOUR_DISCORD_USER_ID"]
    }
  }
}

Supports any OpenAI-compatible API (OpenAI, OpenRouter, Ollama, etc.). See CONFIG.md for more details.

CLI Reference

…

Run on Minimal Hardware

Picobot was designed for constrained environments:

# Raspberry Pi / ARM device
GOARCH=arm64 CGO_ENABLED=0 go build -ldflags="-s -w" -o picobot ./cmd/picobot

# Old x86 VPS
GOARCH=amd64 CGO_ENABLED=0 go build -ldflags="-s -w" -o picobot ./cmd/picobot

Works on any Linux with 256MB RAM. No runtime dependencies. Just copy the binary and run.

Tech Stack

Picobot is written 100% in pure Go, without any CGO dependencies. All required libraries and assets are statically embedded into the final binary. This design ensures zero external runtime dependencies, fast cold start times, and full portability across all platforms supported by Go.

Project Structure

cmd/picobot/          CLI entry point
embeds/               Embedded assets (sample skills)
internal/
  agent/              Agent loop, context, tools, skills
  chat/               Chat message hub
  channels/           Telegram, Discord, Slack, WhatsApp
  config/             Config schema, loader, onboarding
  cron/               Cron scheduler
  heartbeat/          Periodic task checker
  memory/             Memory read/write/rank
  providers/          OpenAI-compatible provider
  session/            Session manager
docker/               Dockerfile, compose, entrypoint

Roadmap

Want to contribute? Open an issue or PR with your ideas!

Docs

• HOW_TO_START.md — step-by-step getting started guide
• CONFIG.md — full configuration reference
• DEVELOPMENT.md — development, testing, and Docker publishing
• docker/README.md — Docker deployment guide

License

MIT — use it however you want.