monkeybot

monkeybot

Guide a new user from only this skill to a working agent. Installing the skill (npx skills add …) gives you these instructions — it does not install the monkeybot CLI. Always run Tier 0 first unless you already know the toolchain is ready. Day-1 users do not need to clone the monkeybot repo.

Tier 0 — Bootstrap toolchain

Run these checks before anything else. Do not skip to Tier 1 until the CLI probe succeeds.

0. Detect what's already installed

command -v monkeybot && monkeybot --help

If that works, skip to Tier 1.

1. Install prerequisites (only if missing)

Tool	Check	Install
uv	command -v uv	curl -LsSf https://astral.sh/uv/install.sh | sh then export PATH="$HOME/.local/bin:$PATH"
Python 3.11+	uv python find 3.11 or python3 --version	uv python install 3.12

Tell the user what you're installing and why. On macOS/Linux you can run these yourself; on Windows, point them at uv.

2. Install the global CLI

# browser-harness pins Pillow 12. Core 3.12 needs Pillow 13, and
# `uv tool install` ignores the package override unless this file is passed.
# Without it the resolver stays on core 3.10.0.
printf 'pillow>=13\n' > /tmp/monkeybot-overrides.txt
uv tool install --overrides /tmp/monkeybot-overrides.txt monkeybot-cli
monkeybot --help

Upgrade later with uv tool install --reinstall --overrides /tmp/monkeybot-overrides.txt monkeybot-cli.

Do not tell day-1 users to clone human-plus-machine/monkeybot unless they are contributing to the harness itself (see Contributing below).

3. Skill-only users

If the user arrived via skills.sh:

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

…they have this skill only. Walk them through Tier 0: install uv → uv tool install --overrides /tmp/monkeybot-overrides.txt monkeybot-cli (write pillow>=13 into that file first) → verify monkeybot --help. Then continue to Tier 1.

How config works (tell the user this first)

• CLI scaffolds, YAML customizes, then validate. monkeybot new copies packaged defaults from the monkeybot-cli package (monkeybot_cli.scaffold_defaults) and sets model.provider / model.name. After that, customization happens by editing monkeybot_config/monkeybot.yaml and .env, then re-running monkeybot validate --json.
• Three config surfaces:
  • monkeybot_config/monkeybot.yaml — non-secret settings (model, paths, gateway, behavior).
  • .env — secrets and machine-local paths (API keys, GCP project, DB URL).
  • sidecars: monkeybot_config/AGENT.md (system prompt), mcp.json (MCP servers), command_allowlist.yaml.
• Precedence — important: environment variables and .env win over monkeybot.yaml except model.* (provider, name, sampling, context window, summarization model, max turns, cache retention), which is YAML-only. If a user edits YAML but nothing changes, suspect a stale .env shadowing it (the YAML→env mapping lives in runtime_env.py:ENV_MAP).
• Defaults are fine on day one. Most first-time users only touch model, .env credentials, and AGENT.md.

Running CLI commands

After Tier 0, every command below uses monkeybot on PATH.

Tier 1 — Get it talking

The minimum path to one successful chat turn. Do this for every new user.

1. Quick interview

Ask (or infer):

• Bot purpose / name → goes in AGENT.md
• Provider + model (see provider table below)
• Optional features (postgres, sandbox, observability, …) → --with or interactive menus

2. Scaffold

monkeybot new --dest /path/to/bot --provider openai --yes
# Interactive (menus for provider + extras):
# monkeybot new --dest /path/to/bot
# Non-interactive extras:
# monkeybot new --dest /path/to/bot --provider openai --with postgres,sandbox --yes

Creates monkeybot_config/, read-only skills/, writable workspace/, memory/, .env.example, a Dockerfile, and an agent pyproject.toml. Use --force only when overwriting is explicitly requested.

Then:

cd /path/to/bot
uv sync

3. Credentials + system prompt

• Copy .env.example → .env and fill in the keys for your provider (table below).
• Edit monkeybot_config/AGENT.md with the bot's system prompt. Never put secrets in YAML.

Provider table

YAML model.provider	.env credentials (any one)	Add to agent pyproject.toml deps, then uv sync
gemini (or vertex)	GEMINI_API_KEY, or GOOGLE_APPLICATION_CREDENTIALS, or GCP_PROJECT_ID / GOOGLE_CLOUD_PROJECT (ADC)	monkeybot[gemini]
openai	OPENAI_API_KEY	monkeybot[openai]
anthropic	ANTHROPIC_API_KEY	monkeybot[claude]
vertex-claude	GCP_PROJECT_ID / GOOGLE_CLOUD_PROJECT / ANTHROPIC_VERTEX_PROJECT_ID (ADC)	monkeybot[vertex-claude]
aws_bedrock	AWS_ACCESS_KEY_ID / AWS_PROFILE + AWS_REGION	monkeybot[bedrock]
huggingface	HF_TOKEN (or HUGGINGFACE_API_KEY)	monkeybot[huggingface]
ollama-cloud	OLLAMA_API_KEY	monkeybot[ollama]
ollama-local	None required — OLLAMA_BASE_URL (default http://localhost:11434). Requests send keep_alive 24h so prefix KV cache survives idle.	monkeybot[ollama]
ollama	Legacy auto-route (key + blank URL = cloud; explicit URL wins)	monkeybot[ollama]

Agent-first dependencies. The CLI is thin — it does not install provider/storage extras globally. monkeybot new scaffolds a pyproject.toml with the selected provider (and any --with extras). Run plain uv sync in the agent directory. monkeybot run / chat spawn the gateway from that project's interpreter (.venv/bin/python, else uv run python), and doctor checks extras in that same interpreter. For a config-only tree (just monkeybot_config/, no pyproject.toml) the gateway uses the CLI's interpreter when it already has MonkeyBot 3.x (and MemPalace if memory is on). If memory is enabled and that interpreter cannot import MemPalace, run / chat provision a cached CLI-managed venv under ~/.cache/monkeybot/runtimes/ holding monkeybot[memory] pinned to the running core (never rewrites a pyproject.toml). doctor reuses that cache when it is already present. Otherwise extras must be installed in the CLI env (uv tool install --reinstall --overrides /tmp/monkeybot-overrides.txt --with 'monkeybot[<extra>]' monkeybot-cli, with pillow>=13 in that file). A bare uv tool install resolves core 3.10.0.

doctor is the source of truth for credentials and extras — when in doubt, run it and read the remediation field (add monkeybot[<extra>] to agent deps + uv sync).

4. Validate (loop until clean)

monkeybot validate --json --cwd /path/to/bot

• Exit 0 + "ok": true → proceed.
• On failure: read checks[] by stable id, apply remediation, re-run.

5. Doctor

monkeybot doctor --json --cwd /path/to/bot

Confirms Python version, provider extra installed, credentials present, and port free.

6. Smoke test

monkeybot chat --cwd /path/to/bot

Or split terminals: monkeybot run --cwd /path/to/bot then monkeybot chat --attach --cwd /path/to/bot.

One successful turn confirms Tier 1.

Tier 2 — Customize (on demand)

Only reach for these when the interview surfaces a need. Each maps to a monkeybot.yaml section. For purpose, defaults, examples, and the validate/doctor check id of every option, read references/config-sections.md. Don't inline that reference here.

Decision → config map:

User says…	Change
"Run many subagents in parallel"	paths.db_url → Postgres (SQLite locks under concurrency)
"I have a custom web UI"	gateway.cors_allow_origins
"Search the web"	web_search.backend + .env keys (Tavily/Firecrawl)
"Run untrusted code"	sandbox.enabled + SANDBOX_API_KEY
"Use specialist agents"	subagents.personas + monkeybot_config/agents/*.md
"Connect external tools"	mcp.json (mcpServers object), then validate --check-mcp
"Control cost / context size"	model.*
"Restrict dangerous commands"	tools.denied_patterns, command_allowlist.yaml
"Multiple environments"	top-level includes: fragments

Subagents (task tool): without subagent_type, share the parent AGENT.md. With a persona, use that persona's agent_md. Relative paths resolve from the bot project root, not workspace/. Specialize via task / context or named personas. For parallel task fan-out, prefer Postgres: add monkeybot[postgres] to the agent pyproject.toml dependencies, run uv sync, then set DB_URL=postgresql://... in .env.

Observability is mostly env + add monkeybot[observability] to agent deps + uv sync + an OTel collector — not monkeybot.yaml. See docs/observability-runbook.md.

Contributing / developing the harness

Only if the user is changing monkeybot itself (not creating an agent):

git clone https://github.com/human-plus-machine/monkeybot.git
cd monkeybot && uv sync
cd cli && uv sync
uv tool install --editable . --overrides src/monkeybot_cli/overrides.txt

Rules

• Tier 0 before Tier 1 — verify or install the global CLI before scaffolding a bot.
• CLI owns scaffolding — do not duplicate template files manually.
• Secrets in .env only — never commit API keys to monkeybot.yaml.
• Validate after every edit — re-run validate --json whenever you change config.
• Parse JSON — key off checks[].id, not free-form messages.
• HTTP/SSE for chat — the CLI talks to the gateway process; do not import harness gateway code.
• No clone for day-1 users — clone is for harness contributors only.

Command reference

Command	Purpose
new	Scaffold monkeybot_config/, workspace/, memory/, skills/, pyproject.toml, .env.example
refresh	Additive update of packaged YAML defaults on an existing agent (keeps AGENT.md, mcp.json, model)
validate	Config + paths + MCP shape (--check-mcp for network)
doctor	Python, provider extra, credentials, port
run	Start SSE gateway subprocess
chat	Interactive terminal client (SSE)
talk	Realtime WebSocket client (audio/text)