monkeybot

Multi-cloud agent harness — GCP-first docs, portable runtime

monkeybot is an owned agent runtime for tool-using LLMs: a FastAPI SSE gateway, pluggable storage, MCP tools, skills, and memory. Run locally with zero cloud dependencies, or ship the same container image anywhere Docker runs.

Docs and examples are GCP-first (Vertex, GCS, Cloud Run); AWS paths ship in the Pattern guides. See Cloud deployment — Positioning.

[!NOTE] Skills under SKILLS_PATH execute Python code — only add skills from trusted sources.

Quick start

Install uv, then:

uv tool install monkeybot-cli

monkeybot new --dest ./my-agent --provider openai --yes
cd my-agent
uv sync
cp .env.example .env   # add provider keys
monkeybot doctor
monkeybot chat

Upgrade the CLI with uv tool upgrade monkeybot-cli. Full walkthrough: Getting Started.

What you get

SSE gateway — sessions, streaming, health; wire your own UI or use the CLI
Realtime talk — WebSocket voice/text via monkeybot talk
MCP + skills — stdio/HTTP tools and trusted Python skill bundles
Pluggable storage — SQLite by default; Postgres, Firestore, GCS, S3
Multi-provider — Gemini/Vertex, OpenAI, Anthropic, Bedrock, Ollama, and more

CLI

Command	Purpose
`monkeybot new`	Scaffold config, workspace, agent `pyproject.toml`, `.env.example`
`monkeybot validate`	Check `monkeybot.yaml`, paths, and MCP config
`monkeybot doctor`	Verify Python, extras, credentials, and port
`monkeybot run`	Start the SSE gateway in the foreground
`monkeybot chat`	Talk over SSE (spawns the gateway; `--attach` to join one)
`monkeybot talk`	Realtime voice/text over WebSocket (`--text` for typed input)

monkeybot chat            # spawn gateway + REPL
monkeybot run             # terminal 1: gateway with logs
monkeybot chat --attach   # terminal 2: attach to it

Provider extras live on the agent pyproject.toml (monkeybot[<provider>]), not the global CLI. See Getting Started and Features — CLI.

Agent skill

npx skills add human-plus-machine/monkeybot --skill monkeybot

Walks through install, scaffold, config, and first chat. Source: cli/skills/monkeybot/.

Documentation

Guide	Description
Getting Started	Install, configure, sessions + SSE from the CLI
Features	Architecture, capabilities, CLI, task queue
SSE gateway and custom UI	HTTP + SSE endpoints, event types, CORS
Skills	Skill directory layout and `SKILL.md` discovery
Model Context Protocol	MCP config, env interpolation, OAuth2
Cloud deployment	Positioning + Patterns A–D index
Live evals	Smoke suite, local + CI scorecard
Observability	OpenTelemetry tracing runbook

Integrations matrix and roadmap: CHANGELOG · BACKLOG.

Contributing

Clone only if you are changing the harness. Setup, checks, and the release workflow are in CONTRIBUTING.md. Live eval smoke fixture: evals/smoke_agent/.

Support

Search or open an issue in the GitHub issue tracker.

License

MIT — see LICENSE.

Monkeybot

README