Picoclaw

PicoClaw

Overview

PicoClaw is an ultra-lightweight personal AI assistant that runs on devices with as little as 10 MB RAM and boots in under 1 second. It connects to LLM providers (OpenRouter, Anthropic, OpenAI, Gemini, DeepSeek, Groq, Zhipu) and bridges conversations to messaging platforms via a gateway. Configuration lives in ~/.picoclaw/config.json.

Instructions

1. Install PicoClaw

From source (recommended for development):

git clone https://github.com/sipeed/picoclaw.git
cd picoclaw
make deps
make build      # binary at build/picoclaw
make install    # installs to ~/.local/bin

From prebuilt binary: download from GitHub Releases for linux-amd64, linux-arm64, linux-riscv64, darwin-arm64, or windows-amd64.

With Docker Compose:

git clone https://github.com/sipeed/picoclaw.git && cd picoclaw
cp config/config.example.json config/config.json
# Edit config/config.json with your API keys
docker compose --profile gateway up -d

2. Initial setup

picoclaw onboard    # creates ~/.picoclaw/config.json interactively

This generates the config file and workspace directory at ~/.picoclaw/workspace/.

3. Configure an LLM provider

Edit ~/.picoclaw/config.json. Set the model and at least one provider API key:

{
  "agents": {
    "defaults": {
      "workspace": "~/.picoclaw/workspace",
      "model": "anthropic/claude-sonnet-4-5-20250929",
      "max_tokens": 8192,
      "temperature": 0.7,
      "max_tool_iterations": 20
    }
  },
  "providers": {
    "openrouter": {
      "api_key": "sk-or-v1-YOUR_KEY"
    }
  }
}

Supported providers: openrouter, anthropic, openai, gemini, zhipu, deepseek, groq, nvidia, moonshot, vllm. Each accepts api_key and optional api_base.

4. Chat with the agent

picoclaw agent -m "Summarize the Go 1.22 release notes"   # single query
picoclaw agent                                              # interactive mode

5. Set up a messaging gateway

Enable one or more channels in config.json, then start the gateway:

Each channel needs enabled: true, a bot token, and an allow_from list of user IDs. Example for Telegram (create bot via @BotFather, get user ID from @userinfobot):

{
  "channels": {
    "telegram": { "enabled": true, "token": "123456:ABC-TOKEN", "allow_from": ["USER_ID"] }
  }
}

Discord: create bot at discord.com/developers/applications, enable MESSAGE CONTENT INTENT, invite with bot scope. Slack: use bot_token + app_token. Other channels: line, dingtalk, qq, feishu, onebot, whatsapp, maixcam.

Start the gateway:

picoclaw gateway

6. Enable web search

Add a Brave Search API key (2000 free queries/month) or use DuckDuckGo as fallback:

{
  "tools": {
    "web": {
      "brave": { "enabled": true, "api_key": "BSA-YOUR-KEY", "max_results": 5 },
      "duckduckgo": { "enabled": true, "max_results": 5 }
    }
  }
}

7. Scheduled tasks and heartbeat

Heartbeat reads ~/.picoclaw/workspace/HEARTBEAT.md every N minutes and executes tasks:

{
  "heartbeat": { "enabled": true, "interval": 30 }
}

Write tasks in HEARTBEAT.md:

## Quick Tasks
- Report current system uptime

## Long Tasks (use spawn for async)
- Search the web for security advisories and summarize

Cron jobs for one-time or recurring reminders:

picoclaw cron list                 # list scheduled jobs
picoclaw cron add "every 2 hours"  # add recurring job

8. Workspace and security

Workspace at ~/.picoclaw/workspace/ contains: sessions/ (history), memory/ (MEMORY.md), cron/ (scheduled jobs), skills/, plus markdown files for agent identity (IDENTITY.md, SOUL.md, AGENTS.md, USER.md, TOOLS.md, HEARTBEAT.md).

By default restrict_to_workspace: true sandboxes all file/exec operations to the workspace. Dangerous commands (rm -rf, mkfs, fork bombs, shutdown) are blocked even when restrictions are disabled. Override with PICOCLAW_AGENTS_DEFAULTS_RESTRICT_TO_WORKSPACE=false.

Examples

Example 1: Deploy PicoClaw as a Telegram bot on a Raspberry Pi

User request: "Set up PicoClaw on my Raspberry Pi as a Telegram bot using Claude"

1. SSH into the Pi and install from source:

git clone https://github.com/sipeed/picoclaw.git
cd picoclaw && make deps && make build && make install
picoclaw onboard

2. Edit ~/.picoclaw/config.json:

{
  "agents": {
    "defaults": {
      "model": "anthropic/claude-sonnet-4-5-20250929",
      "max_tokens": 4096,
      "temperature": 0.7,
      "max_tool_iterations": 10
    }
  },
  "providers": {
    "openrouter": { "api_key": "sk-or-v1-abc123" }
  },
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "7654321:AAF-rG3example",
      "allow_from": ["198234567"]
    }
  },
  "heartbeat": { "enabled": true, "interval": 60 }
}

3. Start the gateway:

picoclaw gateway

The bot now responds to messages in Telegram from the allowed user.

Example 2: Run PicoClaw with Docker Compose and Discord

User request: "Run PicoClaw in Docker with Discord and web search enabled"

1. Clone and configure:

git clone https://github.com/sipeed/picoclaw.git && cd picoclaw
cp config/config.example.json config/config.json

2. Edit config/config.json:

{
  "agents": { "defaults": { "model": "google/gemini-2.5-flash" } },
  "providers": { "openrouter": { "api_key": "sk-or-v1-xyz789" } },
  "channels": {
    "discord": {
      "enabled": true,
      "token": "MTIzNDU2Nzg5.example.token",
      "allow_from": ["987654321012345678"]
    }
  },
  "tools": {
    "web": {
      "duckduckgo": { "enabled": true, "max_results": 5 }
    }
  }
}

3. Start with Docker Compose:

docker compose --profile gateway up -d
docker compose logs -f picoclaw-gateway   # verify it connected

To ask a one-shot question via Docker:

docker compose run --rm picoclaw-agent -m "What is the weather in Tokyo?"

Guidelines

• Always set allow_from with specific user IDs in production to prevent unauthorized access to your bot.
• Only one gateway instance can run per bot token — running two causes Telegram "conflict: terminated by other getUpdates" errors.
• PicoClaw is in early development (pre-v1.0). Do not deploy to production environments with sensitive data.
• When restrict_to_workspace is true, all file and exec operations are sandboxed to the workspace directory. Subagents and heartbeat tasks inherit the same restriction.
• Groq provides free Whisper-based voice transcription. If configured, Telegram voice messages are transcribed automatically.
• Environment variables override config.json values using the pattern PICOCLAW_SECTION_KEY (e.g., PICOCLAW_HEARTBEAT_INTERVAL=60).
• Keep the model name prefixed with the provider when using OpenRouter (e.g., anthropic/claude-sonnet-4-5-20250929). For direct provider connections, use the bare model name (e.g., glm-4.7 for Zhipu).