Concept · Building agents · 4 min read

Building agents in Kaptain

A good Kaptain agent is a kapsule with one job, a bounded workspace, a deliberately chosen model, and settings that survive nobody being at the keyboard. Every control named here is a real switch in the Kapsules tab.

Start with one role

Begin with one responsibility specific enough to evaluate: watch the task board, summarize overnight logs, draft release notes. The Purpose field plus Generate persona drafts the system prompt from exactly that one line — then you edit it. If two jobs need different tools or different review rules, that's two kapsules; if they differ cosmetically, it's one.

Bound the workspace

The agent reasons about the project folder and maintains its own <name>_workspace/; its kapsule folder is read-only to it. Trusted scopes widen access per target — one path with rw, one MCP server, one web host — never per tool. This is what keeps an agent a specialist instead of a vague global helper.

Pick the model route for the job

A monitoring agent is fine on a local 4B; an architecture reviewer wants your strongest route. The kapsule's model field accepts anything in the picker — local, cloud, a CLI harness, even another machine's model over the mesh — and empty means the engine default, so fleet-wide upgrades happen in one place.

Tools and permissions decide what unattended means

The tool allowlist is edited in the kapsule's Tools panel (empty = full enabled catalog, still gated). The approval mode is the real unattended-operation decision: Ask stops a scheduled run at its first risky step; Full access is the only mode that runs a CLI-harness kapsule start to finish with nobody there. Set it deliberately, per kapsule — it ships in the file.

Memory

Off by default, for a reason: replayed history compounds. Turn Remember previous runs on only when the job builds on its own last answer, and reach for Reset run memory the day a bad run poisons the thread. The full reasoning: Schedules and run memory.

Schedules

daily@08:30 in your timezone, results persisted with traces, each occurrence at most once. Review the first few scheduled runs in BlackBox before trusting one unattended — that's what the traces are for.

Agent-readable version: index.md