🐸 Pepebot

Ultra-Lightweight Personal AI Agent

Pepebot is an ultra-lightweight and efficient personal AI agent. Pepebot is designed to provide a powerful AI assistant experience while maintaining minimal resource usage.

• 🤖 Multi-Provider LLM: Support for various AI providers including Anthropic, OpenAI, OpenRouter, Groq, Zhipu, Gemini, Google Vertex AI, MAIA Router and vLLM
• 💬 Multi-Channel: Integration with Telegram, Discord, WhatsApp, MaixCam, and Feishu
• 🛠️ Tools System: Filesystem operations, shell execution, web search, and more
• 📱 Android Automation: ADB tools for device control and UI automation
• 🎬 ADB Activity Recorder: Record device interactions (taps, swipes) and auto-generate workflow files
• 🔄 Workflow System: Multi-step automation with variable interpolation and LLM-driven goals
• 🎯 Skills System: Customizable and extensible skill system
• 🚀 Lightweight & Fast: Small binary size with high performance
• 🔧 Gateway Server: HTTP server for custom integrations
• 💻 Web Dashboard: Modern Web UI accessible online at dash.pepebot.space
• 🎙️ Voice Support: Audio/voice message transcription

Pepebot's dashboard is hosted at dash.pepebot.space — there is no built-in dashboard in the gateway. To use it:

1. Start your gateway: pepebot gateway
2. Go to dash.pepebot.space and register your gateway address (e.g. 127.0.0.1:18790)

Remote gateway? Use SSH tunneling to expose it locally, then register 127.0.0.1:18790 on the dashboard:

ssh -L 18790:127.0.0.1:18790 <user>@<remote-host>

Install the latest release with our automated installer:

curl -fsSL https://raw.githubusercontent.com/pepebot-space/pepebot/main/install.sh | bash

Or download and inspect first:

curl -fsSL https://raw.githubusercontent.com/pepebot-space/pepebot/main/install.sh -o install.sh
chmod +x install.sh
./install.sh

What it does:

• Detects your OS and architecture automatically
• Downloads the latest release binary
• Installs to ~/.local/bin/pepebot
• Optionally sets up systemd (Linux) or launchd (macOS) service
• Adds pepebot to your PATH

Supported systems:

• Linux (x86_64, ARM64, ARMv7, ARMv6, RISC-V, MIPS variants)
• macOS (Intel, Apple Silicon)
• FreeBSD (x86_64, ARM64)

# Add tap (first time only)
brew tap pepebot-space/tap https://github.com/pepebot-space/homebrew-tap

# Install
brew install pepebot

# Start as service (optional)
brew services start pepebot

# Install from GitHub
nix-env -if https://github.com/pepebot-space/pepebot/archive/main.tar.gz

# Or add to your configuration.nix
environment.systemPackages = with pkgs; [
  (callPackage (fetchFromGitHub {
    owner = "pepebot-space";
    repo = "pepebot";
    rev = "v0.5.0";
    sha256 = "...";
  }) {})
];

Production-ready Docker image with cron daemon, tmux, and systemctl replacement for service management.

# Pull image
docker pull ghcr.io/pepebot-space/pepebot:latest

# Run interactively
docker run -it --rm \
  -v ~/.pepebot:/root/.pepebot \
  ghcr.io/pepebot-space/pepebot:latest onboard

# Run as daemon (gateway mode with cron)
docker run -d \
  --name pepebot \
  -v ~/.pepebot:/root/.pepebot \
  -p 18790:18790 \
  ghcr.io/pepebot-space/pepebot:latest gateway

# Using Docker Compose (Recommended)
curl -O https://raw.githubusercontent.com/pepebot-space/pepebot/main/docker-compose.yml
docker-compose up -d

What's included:

• ⏰ Cron daemon (auto-started with gateway)
• 🖥️ Tmux for session management
• 🔧 Systemctl replacement for service control
• 🐧 Ubuntu 24.04 LTS base

For detailed Docker/Podman deployment with cron jobs and tmux, see Docker Deployment Guide.

Same production features as Docker (cron, tmux, systemctl). Perfect for rootless containers!

# Create volume
podman volume create pepebot-data

# Run interactively
podman run -it --name pepebot \
  -v pepebot-data:/root/.pepebot \
  ghcr.io/pepebot-space/pepebot:latest onboard

# Run as background service (with cron)
podman run -d --name pepebot \
  --restart=always \
  -v pepebot-data:/root/.pepebot \
  -p 18790:18790 \
  ghcr.io/pepebot-space/pepebot:latest gateway

# Or use bind mount
mkdir -p ./pepebot-data
podman run -d --name pepebot \
  -v $(pwd)/pepebot-data:/root/.pepebot \
  -p 18790:18790 \
  ghcr.io/pepebot-space/pepebot:latest gateway

All configuration, sessions, skills, and workflows persist in /root/.pepebot. See Docker Deployment Guide for cron setup.

Download pre-built binaries from GitHub Releases:

# Example for Linux x86_64
wget https://github.com/pepebot-space/pepebot/releases/latest/download/pepebot-linux-amd64.tar.gz
tar xzf pepebot-linux-amd64.tar.gz
sudo mv pepebot-linux-amd64 /usr/local/bin/pepebot

Prerequisites:

• Go 1.21 or higher
• Git

# Clone repository
git clone https://github.com/pepebot-space/pepebot.git
cd pepebot

# Build binary
make build

# Install to system (default: ~/.local/bin)
make install

# Build for all platforms
make build-all

Supported platforms:

• Linux (x86_64, ARM64, RISC-V)
• macOS (x86_64, ARM64)
• Windows (x86_64)
• Android (ARM64) 📱 - See Android Setup Guide for Termux setup

# Build Android binary
make build-android

For detailed Android setup instructions, see Android Setup Guide.

# Copy configuration template
cp config.example.json ~/.pepebot/config.json

# Edit as needed
nano ~/.pepebot/config.json

{
  "agents": {
    "defaults": {
      "workspace": "~/.pepebot/workspace",
      "model": "maia/gemini-2.5-flash",
      "provider": "",
      "max_tokens": 8192,
      "temperature": 0.7,
      "max_tool_iterations": 20
    }
  }
}

The default model is set to maia/gemini-2.5-flash which uses MAIA Router. You can change this to any supported model from the providers below.

Provider Option: Set provider to explicitly choose a provider instead of auto-detecting from the model name. Supported values: vertex, maiarouter, openrouter, anthropic, openai, gemini, zhipu, groq, vllm, opencodego.

MAIA Router (Recommended)

MAIA Router is a universal AI gateway that provides access to 200+ AI models (including 52+ free models) through a single OpenAI-compatible API. Perfect for Indonesian users with local payment support (QRIS).

{
  "agents": {
    "defaults": {
      "model": "maia/gemini-2.5-flash"
    }
  },
  "providers": {
    "maiarouter": {
      "api_key": "YOUR_MAIA_API_KEY",
      "api_base": "https://api.maiarouter.ai/v1"
    }
  }
}

To get your API key:

1. Visit maiarouter.ai or router.maia.id
2. Create an account
3. Generate your API key from the dashboard

Popular models available:

• maia/gemini-2.5-flash (Recommended, free tier available)
• maia/gemini-2.5-flash
• maia/claude-3-5-sonnet
• maia/gpt-4o
• And 200+ more models

Anthropic (Claude)

{
  "providers": {
    "anthropic": {
      "api_key": "sk-ant-xxx",
      "api_base": ""
    }
  }
}

OpenAI

{
  "providers": {
    "openai": {
      "api_key": "sk-xxx",
      "api_base": ""
    }
  }
}

OpenRouter

{
  "providers": {
    "openrouter": {
      "api_key": "sk-or-v1-xxx",
      "api_base": ""
    }
  }
}

Groq

{
  "providers": {
    "groq": {
      "api_key": "gsk_xxx",
      "api_base": ""
    }
  }
}

Zhipu (GLM)

{
  "providers": {
    "zhipu": {
      "api_key": "xxx",
      "api_base": ""
    }
  }
}

Google Vertex AI (Service Account)

{
  "agents": {
    "defaults": {
      "model": "gemini-2.0-flash",
      "provider": "vertex"
    }
  },
  "providers": {
    "vertex": {
      "credentials_file": "/path/to/account_services.json",
      "project_id": "your-gcp-project-id",
      "region": "global"
    }
  }
}

To set up Vertex AI:

1. Go to Google Cloud Console
2. Create a service account with Vertex AI permissions
3. Download the JSON key file
4. Set credentials_file to the path of the JSON key file

OpenCode Go OpenCode Go provides low-cost access to open coding models hosted globally (US, EU, Singapore). Uses Anthropic Messages API format.

Important: Set the provider field to opencodego when using OpenCode Go models to avoid conflicts with other providers.

{
  "agents": {
    "defaults": {
      "model": "minimax-m3",
      "provider": "opencodego"
    }
  },
  "providers": {
    "opencodego": {
      "api_key": "YOUR_OPENCODE_API_KEY"
    }
  }
}

To get your API key:

1. Visit opencode.ai/auth
2. Subscribe to OpenCode Go ($5 first month, then $10/month)
3. Copy your API key

Available models (full list: GET https://opencode.ai/zen/go/v1/models):

• minimax-m3 (Recommended, high volume limit), minimax-m2.7, minimax-m2.5
• kimi-k3, kimi-k2.7-code, kimi-k2.6, kimi-k2.5
• glm-5.3, glm-5.2, glm-5.1, glm-5
• deepseek-v4-pro, deepseek-v4-flash
• qwen3.8-max, qwen3.7-max, qwen3.7-plus
• mimo-v2.5-pro, hy3, grok-4.5, gpt-5.6-luna

Environment variables:

export OPENCODEGO_API_KEY="your-api-key"
export PEPEBOT_AGENTS_DEFAULTS_MODEL="minimax-m3"
export PEPEBOT_AGENTS_DEFAULTS_PROVIDER="opencodego"

Telegram Bot

{
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11",
      "allow_from": ["123456789"]
    }
  }
}

Discord Bot

{
  "channels": {
    "discord": {
      "enabled": true,
      "token": "MTIzNDU2Nzg5MDEyMzQ1Njc4OQ.ABCDEF.xxxxxxxxxxxxxxxxxxxxxxxx",
      "allow_from": ["user_id_1", "user_id_2"]
    }
  }
}

WhatsApp (via Bridge)

{
  "channels": {
    "whatsapp": {
      "enabled": true,
      "bridge_url": "ws://localhost:3001",
      "allow_from": ["628123456789@s.whatsapp.net"]
    }
  }
}

MaixCam (IoT Device)

{
  "channels": {
    "maixcam": {
      "enabled": true,
      "host": "0.0.0.0",
      "port": 18790,
      "allow_from": []
    }
  }
}

Feishu (Lark)

{
  "channels": {
    "feishu": {
      "enabled": true,
      "app_id": "cli_xxx",
      "app_secret": "xxx",
      "encrypt_key": "xxx",
      "verification_token": "xxx",
      "allow_from": []
    }
  }
}

{
  "tools": {
    "web": {
      "search": {
        "api_key": "YOUR_BRAVE_API_KEY",
        "max_results": 5
      }
    }
  }
}

{
  "gateway": {
    "host": "127.0.0.1",
    "port": 18790
  }
}

{
  "live": {
    "enabled": true,
    "provider": "vertex",
    "model": "gemini-live-2.5-flash-native-audio",
    "video": false,
    "language": "id-ID",
    "realtime_input_config": {
      "automaticActivityDetection": {
        "disabled": false,
        "startOfSpeechSensitivity": "START_SENSITIVITY_LOW",
        "endOfSpeechSensitivity": "END_SENSITIVITY_LOW",
        "prefixPaddingMs": 80,
        "silenceDurationMs": 1400
      }
    }
  }
}

For voice sessions, realtime_input_config.automaticActivityDetection helps reduce false turn detection/noise triggers:

• language: preferred speech language code for default live speech config (example: id-ID, en-US).
• video: enable live video mode hint in session metadata (video.enabled) so clients can auto-enable camera stream when provider supports it.
• video enables live video capability flag for session metadata and client-side camera streaming flow.
• startOfSpeechSensitivity / endOfSpeechSensitivity: lower sensitivity reduces accidental activation.
• prefixPaddingMs: keeps a small amount of leading audio before VAD start.
• silenceDurationMs: waits longer silence before closing a turn (prevents rapid auto-replies).

Pepebot includes a WebSocket proxy for real-time multimodal streaming (audio, video, text) using the Gemini Live API or OpenAI Realtime API. The WebSocket endpoint is available at ws://localhost:18790/v1/live.

Self-hosted OpenAI Realtime servers: any server that speaks the OpenAI Realtime event protocol on <api_base>/realtime works as the realtime live provider. This is a Live-API-only provider — it never affects chat completions. Point providers.realtime.api_base at it — api_key may be left empty, and no Authorization header is sent when it is:

{
  "providers": {
    "realtime": { "api_base": "http://127.0.0.1:8000/v1", "api_key": "" }
  },
  "live": { "enabled": true, "provider": "realtime", "model": "google/gemma-4-31B-it" }
}

An http:// base becomes ws:// and https:// becomes wss:// automatically. Clients can also select it per session with {"setup": {"provider": "realtime"}} without changing live.provider.

Agent tools and the agent persona work on this provider too: Pepebot sends its tool definitions and the resolved system prompt as a session.update, executes any function_call the model makes, and returns a function_call_output. Whatever else the upstream server lets a client set goes in live.realtime_session, merged into that same frame:

"live": {
  "realtime_session": { "voice": "JV-00027", "temperature": 0.2, "max_response_output_tokens": 200 }
}

Pepebot's own instructions and tools win over the same keys there.

For Vertex/Gemini Live sessions, Pepebot can now expose and execute local agent tools automatically (same tool registry used by normal agent mode). You can select the target agent directly in the setup message:

{
  "setup": {
    "provider": "vertex",
    "model": "gemini-live-2.5-flash-native-audio",
    "agent": "default",
    "enable_tools": true
  }
}

Supported providers:

• vertex (Vertex AI Live API)
• openai (OpenAI Realtime API)
• gemini (Google AI Studio Live API)
• maiarouter (MAIA Router Realtime API)

Live video input support (live.video=true) is explicitly available for:

• vertex
• gemini

When enabled, /v1/live connection confirmation includes:

• video.requested
• video.supported
• video.enabled

Check out the demo clients in the examples/live-api/ directory:

• client.py - A Python console audio streaming client
• client-video.py - A Python console audio + webcam JPEG streaming client
• client-openai.py - A Python console client for OpenAI Realtime event protocol
• index.html - A complete HTML5/JS/Tailwind browser web client using the Web Audio API
• index-video.html - HTML5 voice + camera demo (sends JPEG frames over realtimeInput)
• index-openai.html - HTML5 OpenAI Realtime demo (input_audio_buffer.append, response.audio.delta)
• python/ - Python live client (Poetry) based on the browser implementation
• nodejs/ - Node.js live client based on the browser implementation

pepebot

Then type your commands or questions:

🐸 > Hello! How are you?
🐸 > Create a Python script for web scraping
🐸 > /weather Jakarta

Run workflows directly from the terminal — no agent session needed:

pepebot workflow list                         # List all workflows
pepebot workflow show <name>                  # Inspect a workflow
pepebot workflow run <name>                   # Execute a workflow
pepebot workflow run <name> --var key=value   # Override variables
pepebot workflow run -f ./my_workflow.json    # Run from any file
pepebot workflow validate <name>              # Validate structure
pepebot workflow delete <name>                # Remove a workflow

Run with configured channels:

# Telegram bot
pepebot

# Or use systemd for auto-start
sudo systemctl enable pepebot
sudo systemctl start pepebot

Pepebot supports configuration via environment variables. You can use either PEPEBOT_* prefixed variables or native provider-specific variables.

export PEPEBOT_AGENTS_DEFAULTS_MODEL="claude-3-5-sonnet-20241022"
export PEPEBOT_AGENTS_DEFAULTS_PROVIDER="anthropic"  # Optional: explicit provider
export PEPEBOT_AGENTS_DEFAULTS_MAX_TOKENS=8192
export PEPEBOT_AGENTS_DEFAULTS_TEMPERATURE=0.7
export PEPEBOT_AGENTS_DEFAULTS_WORKSPACE="~/my-workspace"

# Option 1: PEPEBOT_* prefix (recommended for Docker)
export PEPEBOT_PROVIDERS_ANTHROPIC_API_KEY="sk-ant-xxx"
export PEPEBOT_PROVIDERS_OPENAI_API_KEY="sk-xxx"
export PEPEBOT_PROVIDERS_GROQ_API_KEY="gsk_xxx"
export PEPEBOT_PROVIDERS_GEMINI_API_KEY="xxx"

# Option 2: Native provider variables (detected automatically)
export ANTHROPIC_API_KEY="sk-ant-xxx"
export OPENAI_API_KEY="sk-xxx"
export GROQ_API_KEY="gsk_xxx"
export GEMINI_API_KEY="xxx"
export GOOGLE_API_KEY="xxx"  # Alternative for Gemini

# Option 1: PEPEBOT_* prefix
export PEPEBOT_CHANNELS_TELEGRAM_ENABLED=true
export PEPEBOT_CHANNELS_TELEGRAM_TOKEN="123456:ABC-DEF..."

# Option 2: Native bot token variables
export TELEGRAM_BOT_TOKEN="123456:ABC-DEF..."
export DISCORD_BOT_TOKEN="MTk4NjIy..."

export PEPEBOT_TOOLS_WEB_SEARCH_API_KEY="your-brave-api-key"

export PEPEBOT_GATEWAY_HOST="0.0.0.0"
export PEPEBOT_GATEWAY_PORT=18790

Note: During onboarding, Pepebot automatically detects existing environment variables and asks if you want to use them. This makes it easy to integrate with existing CI/CD pipelines or development environments.

For a complete list of all supported environment variables, see .env.example.

Pepebot has an extensible skill system. Skills are prompt templates that provide special capabilities to the bot.

1. github - GitHub operations and automation
2. summarize - Summarize text or documents
3. tmux - Tmux session management
4. weather - Weather information
5. skill-creator - Create new skills

# In CLI
🐸 > /weather Jakarta

# Via bot (Telegram/Discord)
/weather Jakarta

1. Create a new directory at ~/.pepebot/workspace/skills/my-skill/
2. Create a SKILL.md file with the format:

---
name: my-skill
description: My skill description
enabled: true
---

# My Skill Prompt

This is the prompt for my skill.

## Parameters

- param1: Description of parameter 1
- param2: Description of parameter 2

3. Reload or restart the bot to use the new skill

make install-skills

pepebot/
├── cmd/pepebot/          # Main application
├── pkg/
│   ├── agent/            # Agent logic & tool execution
│   ├── bus/              # Event bus for communication
│   ├── channels/         # Channel integrations
│   ├── config/           # Configuration management
│   ├── cron/             # Scheduled tasks
│   ├── heartbeat/        # Health monitoring
│   ├── logger/           # Logging system
│   ├── providers/        # LLM provider interfaces
│   ├── session/          # Session management
│   ├── skills/           # Skills loader & installer
│   ├── tools/            # Tool implementations
│   ├── voice/            # Voice transcription
│   └── workflow/         # Workflow engine & execution
├── skills/               # Built-in skills
├── assets/               # Logo and assets
├── config.example.json   # Configuration template
└── Makefile             # Build automation

# Build for current platform
make build

# Build for all platforms
make build-all

# Format code
make fmt

# Update dependencies
make deps

# Clean build artifacts
make clean

# Build and run
make run

# Show help
make help

# Run tests (if available)
go test ./...

# Run with verbose output
go test -v ./...

🐸 > Explain Go channels

🐸 > Create a hello.py file with a hello world program
🐸 > Read config.json and explain its structure

🐸 > Search for the latest information about Go 1.22

🐸 > Run command: ls -la
🐸 > Check the status of this git repository

Pepebot includes powerful Android automation capabilities via ADB tools and workflows.

# Install ADB (Android Platform Tools)
# macOS
brew install android-platform-tools

# Linux (Debian/Ubuntu)
sudo apt install adb

# Connect device and enable USB debugging
adb devices

• adb_devices - List connected Android devices
• adb_shell - Execute shell commands on device
• adb_tap - Tap screen coordinates
• adb_input_text - Input text to focused field
• adb_screenshot - Capture device screenshots
• adb_ui_dump - Get UI hierarchy (XML)
• adb_swipe - Perform swipe gestures
• adb_record_workflow - Record device interactions and generate workflow files

Create multi-step automation workflows combining ADB, web, file, and shell tools.

Agent Workflow Tools (via chat):

• workflow_execute - Run saved workflows
• workflow_save - Create new workflows
• workflow_list - List available workflows

Workflow CLI (standalone, no agent needed):

# List all workflows
pepebot workflow list

# Show workflow details (steps, variables, types)
pepebot workflow show my_workflow

# Run a workflow from workspace
pepebot workflow run my_workflow

# Run with variable overrides
pepebot workflow run my_workflow --var device=emulator-5554 --var query=hello

# Run directly from any JSON file (bypass workspace)
pepebot workflow run -f /path/to/workflow.json

# Validate workflow structure before deploying
pepebot workflow validate my_workflow

# Delete a workflow
pepebot workflow delete my_workflow

Cron / scripting:

# Schedule with cron (tool-only workflows, no LLM needed)
0 * * * * pepebot workflow run device_health --var device=emulator-5554

# Multi-device batch
for device in emulator-5554 emulator-5556; do
  pepebot workflow run device_health --var device="$device"
done

# CI/CD — run workflow from repo
pepebot workflow run -f ./ci/workflows/smoke_test.json --var env=staging

Tip: Workflows with only tool steps run standalone without an LLM. Add goal/agent steps only when you need LLM reasoning. See Workflow Documentation for full details.

For comprehensive guides and technical documentation, visit our documentation hub:

• Installation Guide - Complete installation instructions for all platforms
• Workflow System - Multi-step automation framework documentation
• API Documentation - REST API and integration interfaces
• Android Setup - Android-specific setup and Termux instructions
• Build Guide - Build instructions and CI/CD documentation

./build/pepebot agent -m "execute quick_check workflow dengan device 001a6de80412"

Time: ~5s | Output: Device list, Android version, screenshot

./build/pepebot agent -m "jalankan device_control workflow untuk device 001a6de80412 dan berikan analisis lengkap tentang kesehatan device"

Time: ~10s | Output: Battery, memory, storage, network report

./build/pepebot agent -m "buatkan workflow bernama 'app_launcher' yang: 1) cek device connected, 2) launch aplikasi chrome dengan command 'am start -n com.android.chrome/com.google.android.apps.chrome.Main', 3) tunggu 2 detik, 4) ambil screenshot. Simpan dengan workflow_save"

Time: ~8s | Output: New workflow JSON file created

./build/pepebot agent -m "buat dan eksekusi workflow yang mengambil 3 screenshot dengan nama screen_1.png, screen_2.png, screen_3.png dari device 001a6de80412"

Time: ~15s | Output: 3 PNG files (4 MB each)

./build/pepebot agent -m "buat workflow 'device_monitor' yang: 1) ambil battery level, 2) ambil memory usage, 3) ambil top 5 running processes, 4) simpan semua info ke file device_report.txt, 5) ambil screenshot sebagai bukti. Lalu execute workflow tersebut untuk device 001a6de80412"

Time: ~12s | Output: Text report + screenshot

• API Keys: Don't commit config.json file to git
• Allow List: Use allow_from to restrict access
• Permissions: Tools have access to filesystem and shell
• Network: Gateway server is exposed on the network (watch your firewall)

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Create a Pull Request

This project is licensed under the MIT License - see the LICENSE file for details.

• Inspired by nanobot from HKUDS
• Built with ❤️ using Go

• Issues: GitHub Issues
• Discussions: GitHub Discussions