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) |
| Run on a coding agent (ACP runtime) | You want an external coding agent (proto/Codex/Claude/Copilot/OpenCode) to be the runtime brain, with protoAgent as the shell |
| Run on Hermes (preset) | You already run Hermes Agent and want protoAgent's console/A2A/scheduler wrapped around it — one command |
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 |
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 |
| Spawn CLI coding agents (ACP) | You want the agent to drive a CLI coding agent (e.g. protoCLI) over the Agent Client Protocol |
| 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 |
Tools, MCP & plugins
Add capability without forking — external tools, drop-in packages, channels.
| Guide | When to read |
|---|---|
| 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) |
| Discord surface | You want the agent reachable from Discord (the first-party discord plugin) |
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 |
| 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 |
| 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 |
|---|---|
| Deploy via GHCR | You're ready to ship and want auto-deploy wired up |
| 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 |
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 |