meshbot

Quick Start

Install and run

bun install
bun run typecheck
bun run start

Dashboard and API default to http://localhost:8787. Use RUN_DEMO=1 bun run start to enqueue sample tasks.

Configuration

export AGENT_BACKEND=pi-coding-sdk
export PI_MODEL=openai:gpt-4.1-mini
export OPENAI_API_KEY=sk-...
bun run start

Backends: pi-ai, pi-coding-sdk, pi-subprocess. Set PI_MODEL=provider:model for the target LLM.

Features

• Autonomous + Delegated

  Run delivery flows automatically or dispatch focused tasks to planner, coder, reviewer, tester, and architect roles.

• Skill-Aware

  Dynamic agents choose tools and installed skills from a safe registry and execute with policy checks.

• Scheduled Ops

  Use interval or cron-style schedules to run recurring tasks, campaigns, and dynamic runs.

• Channel Control

  Trigger tasks from Telegram or Discord relay with pairing, allowlists, and audit-ready runtime logs.

• Reliability

  Configurable concurrency, retry with backoff, dead letter queues, and event sourcing with file or SQLite stores.

• Webhooks

  Push task events to external services with bearer tokens, signing secrets, and event filtering.

• Multi-Provider

  Supports OpenAI, Anthropic, Gemini, Azure OpenAI, Bedrock, Vertex, and any OpenAI-compatible provider.

• Identity & Guardrails

  Role-based agent instructions, global guardrails, reusable prompts, and extension-based delegation.

Setup

Reliability and persistence

export ORCHESTRATOR_MAX_CONCURRENCY=4
export ORCHESTRATOR_RETRY_MAX_ATTEMPTS=3
export ORCHESTRATOR_RETRY_BACKOFF_MS=2000
export EVENT_STORE=sqlite
export EVENT_STORE_SQLITE_PATH=./data/events.db

Webhooks

export WEBHOOK_URL=https://example.com/hook
export WEBHOOK_BEARER_TOKEN=your-token
export WEBHOOK_SIGNING_SECRET=your-secret
export WEBHOOK_EVENTS=task.completed,task.failed

Skills

• Registry file: .pi/skill-registry.json
• Allowlist: SKILL_REGISTRY_ALLOWED_REPOS
• Installed skills: .pi/skills

Providers and Model Keys

Agents, Identity, and Prompts

• AGENTS.md for global guardrails
• IDENTITY.md for system behavior and invariants
• .pi/agents/*.md for role instructions
• .pi/prompts/*.md for reusable prompts
• .pi/extensions/a2a-bridge for extension-based delegation

Scheduler

Run recurring jobs with API-managed schedules. Supports both interval and cron modes.

# Interval-based schedule
curl -s -X POST http://localhost:8787/schedules \
  -H 'content-type: application/json' \
  -d '{
    "name":"10m health check",
    "mode":"interval",
    "intervalMs":600000,
    "task":{"kind":"delivery","goal":"Summarize queue health"}
  }'

# Cron-based schedule
curl -s -X POST http://localhost:8787/schedules \
  -H 'content-type: application/json' \
  -d '{
    "name":"Nightly run",
    "mode":"cron",
    "cron":"0 2 * * *",
    "task":{"kind":"dynamic","goal":"Nightly hardening"}
  }'

Channels

Telegram

1. Create bot in BotFather.
2. Set TELEGRAM_BOT_TOKEN.
3. Set webhook to meshbot endpoint.

curl -s "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/setWebhook?url=https://<host>/channels/telegram/webhook"

Discord

Use a lightweight relay bot/worker that sends channel messages to /channels/discord/webhook.

{ "content": "/task delivery Improve queue analytics", "userId": "123", "channelId": "456" }

Set DISCORD_WEBHOOK_URL for outbound notifications.

Security default: channel users are blocked until allowlisted or paired. Generate pairing codes with admin token and complete with /pair <code>.

API Examples

# Submit a delivery task
curl -s -X POST http://localhost:8787/tasks/delivery \
  -H 'content-type: application/json' \
  -d '{"goal":"Implement retry-safe event compaction"}'

# Create and run a dynamic agent
curl -s -X POST http://localhost:8787/agents/dynamic/create-and-run \
  -H 'content-type: application/json' \
  -d '{
    "goal":"Implement skill-aware routing",
    "requirements":"Select tools and skills then execute",
    "preferredSkills":["gabrielkoerich-skills"],
    "autoInstallSkills":true
  }'

View full documentation and source on GitHub →