Guide · October 16, 2026 · 6 min read

What is a kapsule?

A model answers questions. An agent does a job. The difference is the harness around the model: its instructions, tools, permissions and memory. This guide builds a harness from first principles, then shows how a Kaptain kapsule packages one, and how several kapsules work together.

A model on its own

A language model takes text in and gives text out. Send it the same question twice with no history and it starts from nothing each time. It has no hands: it cannot read your files, run your tests or check its own answer. It has no job either. Unless something tells it, it does not know what it is for or when to stop.

That is fine for a one-off question. It is not enough for work you want done every day, such as “summarize last night’s logs” or “draft release notes from the changelog”. For that, the model needs a structure around it.

What a harness is

A harness is the program that wraps a model and turns it into a worker. If you built one from scratch, you would need five parts:

1. Instructions. Standing text that says what the job is and how to do it, often called a system prompt.
2. Tools. The actions the model may ask for, such as reading a file or searching the web. The second guide explains tool calls.
3. Permissions. Which of those actions run on their own, and which wait for a person.
4. Memory and context. What the model is shown on each turn: the task, earlier messages, what it learned before. What is left out matters just as much, because a model’s context window, the amount of text it can take in at once, is finite.
5. A loop. Send the context, run the tool calls the model asks for, return the results, and stop when the model answers or a limit is reached.

Claude Code and Codex are harnesses. So is a Kaptain chat with Tools on. A kapsule is a harness you define yourself. In the words of Kaptain Docs, it is “a harness, not just a prompt.”

What a kapsule packages

A kapsule is an agent you define as a folder: a model wrapped with a persona, a tool allowlist, a permission mode, skills, memory and an optional schedule. It has its own chats, its own jobs and its own workspace. Its definition is one kapsule.json file you can diff, copy and keep in git.

The division of labour is simple: “The model decides how to think; the kapsule fixes what it may touch, how much it may do unattended, and what it remembers.” Each harness part has a place:

The fields sit under agent in the file. A small but complete kapsule looks like this:

{
  "name": "news-digest",
  "agent": {
    "system": "You write a short morning digest of AI news.",
    "model": "qwen3:8b",
    "tools": ["web_search", "web_fetch", "file_write", "time_now"],
    "task": "Write today's digest to news-digest_workspace/digest.md",
    "schedule": "daily@08:30",
    "approval_mode": "auto",
    "memory": false
  }
}

Scopes and safety

An agent that runs at 3 a.m. has nobody to ask. Its limits have to be set before it starts, and they have to hold.

• Its own workspace. The agent reasons over your project but writes freely only in its own <name>_workspace/ folder. Its kapsule folder is read-only to it.
• Permissions decide what unattended means. On Ask, a scheduled run stops at its first risky step and reports what it could not do. Auto-approve in workspace and Full access run without prompts. On a Claude Code or Codex model whose own approval you set, the stricter of the two applies, so a kapsule can never widen what you allowed the CLI.
• Allowed paths name targets, never tools. path:/home/you/reports rw lets every tool read and write that folder; ro, the default, only reads. mcp:<server id> lets the kapsule use one MCP server without a prompt. host:<domain> restricts web tools to the hosts listed. The permission mode stays the ceiling: in Read-only, no entry allows a write.
• Fresh runs by default. Run memory is off, so each scheduled run starts from its task instead of replaying yesterday. A kapsule can still keep one-sentence lessons with the remember tool, kept only when a run finishes cleanly.
• Predictable schedules. The same kapsule never runs twice at once. If Kaptain was not running when a run was due, that run is skipped, not caught up.

Before you trust a schedule, read its first results in Jobs and in BlackBox, Kaptain’s record of every turn.

One agent or several

Start with one kapsule per job. Kaptain Docs suggest a simple test: if two jobs need different tools or different review rules, make two kapsules. Kapsules then work together in two ways.

Calling another kapsule. Every kapsule is also a tool, agent_<name>. A kapsule may call another when its Tools include that agent tool, or when its Delegation is On (auto) or On (aggressive). Off refuses every call. The called kapsule runs with its own model, instructions, tools and permissions, and it cannot see your conversation: it gets a self-contained task and returns its result. Calls nest at most three deep, and a loop is refused. Whatever one agent passes to another is material to work on, never an instruction with the caller’s authority.

Bringing in workers. With Can bring in workers on, a kapsule may split a job across workers it creates for that job. Each worker gets only the tools its part needs, and never more than the kapsule itself. Parts that do not depend on each other run in parallel. Only a worker that completes its part with evidence is kept for reuse.

Why split work this way? A narrow allowlist keeps each mistake small. Each kapsule can run on the model that fits its part, such as a strong model for planning and a local model for reading sources. The cost is real too. Every call is another model run and another hand-off, and a called kapsule sees only the task it was given. Keep the team as small as the job allows.

How to make one

1. Open Kapsules and press + New kapsule.
2. Give it a Name: letters, numbers, - and _. The name becomes its folder and the agent_<name> tool other agents call.
3. Write one line of Purpose and press Generate persona for a draft of its instructions. Edit the Persona freely.
4. Choose a Model. A small local model is fine for watching and summarizing; give judgement-heavy work your strongest route.
5. Tick only the Tools the job needs.
6. Pick a Schedule and write a Standing task. A schedule without a task is refused.
7. Press Create kapsule. It is live at once. Permissions, skills, run memory, allowed paths and delegation are set afterwards under its Settings.

Try it with Run now, or talk to it in its own chats. From a terminal, kaptain agent list shows every kapsule with its model and schedule, and kaptain agent chat <name> "<message>" sends it one message. A kapsule.json you write by hand is read the next time Kaptain starts.

Where to go next

Kaptain Docs covers every field and setting: Kapsules, Design a good kapsule, Kapsule settings, Allowed paths, Schedules and run memory, Agents calling agents and the kapsule.json reference.

This is the third guide in a series. Choose your parts explains why each part of an AI setup should be yours to change, and Krew and MCP explains the tools a kapsule can use.