Concept · Kapsules · 3 min read

What a Kapsule is

Most systems bolt agents, plugins, and prompt-packs on as three different mechanisms. Kaptain has one: the Kapsule — a folder with a kapsule.json that mounts live, carries its own contract, and travels like code.

One folder, one contract

A kapsule lives at kapsules/<name>/ in Kaptain's data folder. Drop it in and it mounts with no restart; delete it and it's gone. Everything the UI edits — persona, model, tools, schedule, permissions — lands in that one JSON file, which means a kapsule can be reviewed in a diff, versioned in git, and handed to another machine as-is.

What a kapsule can carry

Three section kinds, any mix: an agent (persona + model + tool allowlist + optional schedule — this is what the Kapsules tab shows), skills (instruction documents its agent always carries), and an mcp section (its own tool server, spawned and supervised by Kaptain). A kapsule that carries all three is a complete capability: the worker, its knowledge, and its tools in one reviewable folder.

Why it's a file and not a database row

Because contracts you can read are contracts you can trust. The approval mode travels with the kapsule — a git-shipped kapsule carries its own policy instead of inheriting whatever the destination machine felt like. The same logic gives each kapsule a private memory database and a split home: its folder is read-only to the agent (what you gave it), and <name>_workspace/ is read-write (what it maintains).

Its boundaries

A kapsule's agent uses the tools you listed — an empty list means the whole enabled catalog, still gated by its approval mode. Trusted scopes pre-approve targets (a path, one MCP server, one web host), never whole tools. Building one takes two minutes in the UI: How-To ▸ Kapsules.

Agent-readable version: index.md