How-To Guides
Task-oriented procedures, grouped by domain (the same order used across Tutorials, Reference, and Explanation). Assumes you already have a running agent — see Tutorials if not (the wizard runs with zero setup).
Getting started
Fork the template and make it yours.
| Guide | When to read |
|---|---|
| Fork the template (fast path) | Terse checklist for experienced forkers |
| Customize & deploy | You've evaluated via the wizard and now want to fork, rename, and ship your own image |
Agent core & runtime
Shape how the agent's loop behaves — standing goals, timers, middleware hooks, the runtime brain.
| Guide | When to read |
|---|---|
| Goal mode | You want the agent to pursue a standing goal across turns, not just answer one-shot |
| Watches | You want the agent to supervise many external conditions at once — poll a metric, react when it trips |
| Schedule future work | You want the agent to defer tasks to itself ("remind me tomorrow", recurring sweeps) — bundled local sqlite |
| Middleware | You want pre/post hooks on the agent turn (plugin-contributed) |
| System lifecycle events | You want plugins/skills to react to boot, idle-wake, or the desktop shell coming to the foreground (event-bus broadcasts) |
| Run on a coding agent (ACP runtime) | Deprecated — you already run an acp:* runtime and need its reference. For new work, hand coding jobs to an acp delegate instead |
Skills, subagents & workflows
Give the agent reusable, named capabilities and delegates.
| Guide | When to read |
|---|---|
Skills (SKILL.md) | You want to drop in reusable, load-on-demand skill instructions in the AgentSkills SKILL.md format |
| Add a custom skill (A2A card) | You want A2A callers to dispatch a named capability — a card skill, distinct from the SKILL.md skills above |
| Configure subagents | You want specialized delegates beyond the shipped researcher |
| Reusable workflows | You want declarative multi-step recipes (*.yaml) the agent can run on demand |
Verifier-grounded coder (coder_solve) | You want the agent to solve a verifiable coding task via an execution-grounded search ladder (the coder plugin) |
Knowledge & memory
Load content the agent can recall, and tune how it's retrieved.
| Guide | When to read |
|---|---|
| Ingest documents & media | You want to pull files, web pages, PDFs, or audio/video into the knowledge store |
| Tune the knowledge store (RAG) | You want to adjust hybrid retrieval — top_k, vector_k, rrf_k, min_score, embeddings |
A2A, fleet & delegates
Connect your agent to other agents and endpoints, and run many of them.
| Guide | When to read |
|---|---|
| Delegates (agents & endpoints) | You want to manage the agents + endpoints your agent talks to via delegate_to (a2a / openai / acp), hot-swappable from the console |
Rooms (@name group chat) | You want to address a delegate directly from chat, put several of them in one conversation, or tune how far a room runs before it stops |
| CLI coding agents over ACP | You want the agent to hand a coding job to protoCLI / Claude Code / Codex and get the result back — the supported way to use a coding agent |
| Run a fleet (workspaces, archetypes, supervisor) | You want many named agents on one host — created from archetypes, run in the background, sharing a skills commons |
| Portfolio (one PM, many team boards) | You want one PM agent to dispatch work to, and track, several team-agents' project boards across repos — over A2A |
| Agent snapshots (export, share, duplicate) | You want to hand someone your agent's recipe — persona, config, plugin pins, skills — as a small zip, or stand up a duplicate from one |
| Build out your agent with a coding agent | You've forked the template and want to grow it through a project-manager agent, a board, and coder delegates instead of typing every change |
Tools, MCP & plugins
Add capability without forking — external tools, drop-in packages, channels.
| Guide | When to read |
|---|---|
| Extend protoAgent | The map for adding capability without forking — plugins, views, MCP |
| Connect MCP servers | You want to plug external tools into the agent via the Model Context Protocol (stdio / HTTP) |
| Plugins | You want drop-in packages that add tools, skills, routes, background surfaces, subagents and managed MCP servers without forking (Discord ships this way; Google/Slack install as external plugins) |
| Building a plugin view | You want a plugin to add its own console surface — a left-rail view (dashboard/chart/editor) or a panel that replaces the built-in chat |
| Build a communication plugin | You want a new inbound/outbound channel (like Discord) as a plugin surface |
| Install & publish plugins (git URLs) | You want to install a plugin from a git URL, or publish one as a shareable repo (tools + skills + subagents + workflows + views) |
| Bundles | You want several plugins installed, updated, and removed as one tested set — or to publish an archetype repo of your own (manifest, pin lifecycle, verify CI, archetype card) |
| Discord surface | You want the agent reachable from Discord (the first-party discord plugin) |
File GitHub issues (/issue) | You want to file a GitHub issue straight from the console — the /issue command or the util-bar widget |
| Friction log | You want to triage what keeps getting in the agent's way: the Friction view, /friction, filing rows as issues, tuning what reaches its working state, and clearing noise |
Console & UI
Surface the agent to people — the operator console, or no UI at all.
| Guide | When to read |
|---|---|
| Operator console (React/Tauri) | You want the multi-chat React console and to package it for desktop |
| Windows desktop app (install & recovery) | You're installing or troubleshooting the packaged Windows build — supported system, SmartScreen posture, data locations, updates, and recovery |
| Managed Python runtime (desktop) | You're on the desktop app and execute_code / the document skills (docx · xlsx · pptx · pdf) need their one-click interpreter install |
| Command palette (⌘⇧K) | You want the fast keyboard path to jump between surfaces + inline chat |
| Developer flags | You want to merge a half-built feature behind a tiered flag (off/dev/beta/on) instead of a long-lived branch |
| Access from your phone (LAN / Tailscale) | You want to drive the agent from your phone — installable PWA over your LAN or tailnet, add-to-home-screen |
| Pair devices and agents | You want a phone or another protoAgent to get its own revocable token for this agent — QR or typed code, making the agent reachable, revoking, and delegating to a paired remote |
| Run headless (API + A2A) | You want the agent as a service — REST + A2A — with no UI |
Operate & deploy
Ship it, isolate it, fence it in, and watch it.
| Guide | When to read |
|---|---|
The protoagent command (CLI) | You want the terminal control plane — install, run, and manage an instance without the console |
| Deploy via GHCR | You're ready to ship and want auto-deploy wired up |
| Deploy in Docker (config-as-code) | You want a container that boots pre-configured from a baked seed while console edits still persist |
| Deploy on Proxmox (reusable LXC template) | You run Proxmox and want a clone-in-seconds template for test/fleet instances |
| Releasing | You're cutting a versioned release (semver bump → image → GitHub release) |
| Run multiple instances | You want several scoped agents (data isolation) on one host |
| Sandboxing & egress | You want to fence the filesystem + outbound network |
| Expose to the world | You want an agent reachable from the public internet — A2A only, token-gated, console hidden |
| Wire Langfuse + Prometheus | You need traces and metrics in production |
| Operating a fleet (health, rollout, triage, recovery) | You're running a multi-member fleet and need health-check, upgrade, incident-triage, and recovery procedures |
Forks & evals
Build a downstream operator fork, keep it synced, and measure it.
| Guide | When to read |
|---|---|
| Build an operator fork (Roxy) | You're building a portfolio-manager / operator agent on top of the template |
| Sync a fork from upstream | Your fork needs to pull fixes + features down from the template (merge-not-squash) |
| Eval your fork | You want a baseline pass-rate for the tools / memory / A2A surface in your fork |