> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pnbr.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Kit

> A Kit is the set of tools one kind of agent may call in a project. It limits what the agent can do, never what it can read.

Concept · access

> **Use when**
>
> You make or check an agent for the person's project, give it an address or a key, or choose how much it may change.

> **Looking for something else?**
>
> Limiting what an agent reads (card [view](https://docs.pnbr.io/concepts/view.md)). Giving a client agents, access and a list of what they did (card [brain](https://docs.pnbr.io/concepts/brain.md)). The tools you have yourself (card [credential](https://docs.pnbr.io/concepts/credential.md)).

## For

A Kit is a named role for an agent on one project. It lists the tools the agent
may call, and it may add instructions. Each published version of a Kit is fixed
and has an address that opens that role. A person can connect an MCP client to
the address, or you can make a machine connection that has its own key.

A Kit says what an agent may do. It does not say what the agent may read. To
limit what it reads, limit its connection to a View.

## Use when

* The person asks for an agent that works with some of the project's Shapes.
* You must choose how much that agent may change.
* You need the address to add to an MCP client, or a key for a machine.
* A Brain needs agents of its own (card [brain](https://docs.pnbr.io/concepts/brain.md)).

## Not this

* A limit on what an agent or key reads: use a View (card [view](https://docs.pnbr.io/concepts/view.md)).
* The agents and access you give one client, in one place: use a Brain (card
  [brain](https://docs.pnbr.io/concepts/brain.md)).
* Which credential you hold and what it can do: use card [credential](https://docs.pnbr.io/concepts/credential.md).

## Rules

1. `kit.1` A Kit limits actions, not data. **Your job:** to limit what an agent
   reads, create its connection with `--view <view-id>` (card [view](https://docs.pnbr.io/concepts/view.md)). Without a
   View, the agent reads the project as far as its tools and the person who made
   it allow.
2. `kit.2` Describe the agent, and Penumbra chooses its tools. **Your job:** run
   `penumbra kits draft --name "<name>" --shape <shape> --level <level>`. Give 1
   to 20 published Shapes. The Kit level is `read`, `propose`, `confirm` or
   `apply`.
   `read` reads only. `propose` stages changes that a person submits.
   `confirm` changes the project with each change approved first. `apply`
   changes it directly, and the project's approval rules still hold. **Enforced:**
   a Kit level that your role cannot give is refused with `level_unavailable`,
   and the answer names the highest level you can give.
3. `kit.3` Choose the lowest Kit level that does the job. **Your job:** read the
   lines under "an agent with it" that the draft prints, and tell the person
   in those words. The person decides the Kit level, not you.
4. `kit.4` Check a draft, and publish what you checked. **Your job:** run
   `penumbra kits check <kit-id>`. It prints the tools and a review digest.
   Publish with `penumbra kits publish <kit-id> --digest <digest>`. **Enforced:**
   a draft that changed after the check is refused with `kit_draft_changed`.
   Without `--digest`, publish checks the draft itself first.
5. `kit.5` A refused draft says what to fix, field by field. **Enforced:** a
   draft that is saved but not ready exits with code 3 and `kit_not_ready`. The
   output starts with "to fix:" and gives one line for each field. Fix those
   fields and run `penumbra kits draft --kit <kit-id>` again with the same flags.
6. `kit.6` A published version does not change, and a connection keeps the tools
   it was made with. **Enforced:** a newer version of the Kit adds no tool to a
   connection that exists. **Your job:** to give an agent the newer version, make
   a new connection on it.
7. `kit.7` An address grants nothing by itself. **Enforced:** a client that opens
   it signs in, and the person approves it. **Your job:** give the address to
   the person, who adds it to an MCP client such as Claude.
8. `kit.8` A machine connection has its own key, and the key is shown once.
   **Your job:** run `penumbra kits connections create "<name>" --kit <kit-id>`
   and store the key it prints. **Enforced:** Penumbra cannot show the key again,
   and it works for 30 days. The key opens the Kit's address only. The API
   refuses it. If it is lost, the person rotates or revokes the connection in the
   App.
9. `kit.9` Kits and connections belong to a person. **Enforced:** a key or a
   connected agent that runs `penumbra kits list`, or any other Kit command, is
   refused with `human_session_required` and exit code 3. Making a
   connection needs a project owner or admin. Limiting it to a View also needs
   someone who manages access.
10. `kit.10` A connection for a View or a Brain can only read. **Your job:** run
    `penumbra kits show <kit-id>` and use a version that says "reads only".
    **Enforced:** another version is refused with `view_requires_read_only` or
    `brain_kit_not_read_only` (card rules [view.6](https://docs.pnbr.io/concepts/view.md#rule-view-6) and [brain.5](https://docs.pnbr.io/concepts/brain.md#rule-brain-5)).
11. `kit.11` A new Kit is private to the person who made it. **Enforced:** a
    Brain refuses a Kit that is not shared with the project, with
    `brain_kit_unavailable`. **Your job:** the CLI has no command that shares a
    Kit. Ask a project owner or admin to open **Tools**, then **Kits**, and set
    **Who can use this Kit?** to **Members of this project**.
12. `kit.12` A Kit cannot lower the project's approval rules. **Enforced:** every
    connection follows the project's rules for destructive, publication and paid
    changes (card [approval](https://docs.pnbr.io/concepts/approval.md)). Kit level `confirm` also holds every submit for
    approval. **Your job:** do not promise the person that an `apply` agent
    changes the project without a check. Read the consequence lines that the
    draft prints.
13. `kit.13` Instructions are text sent to the client. **Enforced:** more than 8192
    characters is refused. The CLI refuses it before it sends the draft, with
    `invalid_input` and exit code 2. The cell names the same limit
    `instructions_too_long`. A Kit counts characters,
    and a Brain counts bytes (card rule [brain.11](https://docs.pnbr.io/concepts/brain.md#rule-brain-11)). **Your job:** never put a
    secret in them, because the client can read them. They do not change what the
    agent may do.
14. `kit.14` Publishing and making a connection are keyed. **Enforced when you ask:**
    run the same command with the same `--request-id`, and you get the same
    version or connection, not a second one. A repeat of a connection does not
    show the key again. Without the flag, the CLI makes a new key for each run.
15. `kit.15` Retiring a Kit ends every connection on it. **Your job:** tell the
    person before they retire it. Penumbra revokes the connections and cancels
    the approvals that wait for them. The CLI has no command for it. The person
    retires a Kit in the App with **Retire Kit**.

## Failure signs

* The agent reads more than the person meant: it has no View (rule [kit.1](https://docs.pnbr.io/concepts/kit.md#rule-kit-1)).
* `penumbra kits publish` is refused with `kit_draft_changed`: rule [kit.4](https://docs.pnbr.io/concepts/kit.md#rule-kit-4).
* A draft exits with `kit_not_ready`: rule [kit.5](https://docs.pnbr.io/concepts/kit.md#rule-kit-5).
* `penumbra kits list` is refused with `human_session_required`: rule [kit.9](https://docs.pnbr.io/concepts/kit.md#rule-kit-9).
* A Brain refuses the Kit: rules [kit.10](https://docs.pnbr.io/concepts/kit.md#rule-kit-10) and [kit.11](https://docs.pnbr.io/concepts/kit.md#rule-kit-11).
* An agent has a tool that the person did not expect: the Kit version it was
  made with has it (rule [kit.6](https://docs.pnbr.io/concepts/kit.md#rule-kit-6)).
* An agent cannot find something the person sees: problem
  [hidden-reads-as-missing](https://docs.pnbr.io/troubleshooting/hidden-reads-as-missing.md).

## Doors

| Door | Call |
| - | - |
| CLI | `penumbra kits draft`, `penumbra kits check`, `penumbra kits publish`, `penumbra kits list`, `penumbra kits show`, `penumbra kits addresses list`, `penumbra kits addresses create`, `penumbra kits connections list`, `penumbra kits connections create` |
| MCP | none. No tool makes or manages a Kit. Use the CLI. |
| SDK | `kits` |

The CLI has no command that shares, retires, rotates or revokes. The person
does those in the App under **Tools**, then **Kits**.

## Keep going

[View](https://docs.pnbr.io/concepts/view.md) · [Brain](https://docs.pnbr.io/concepts/brain.md) · [Credential](https://docs.pnbr.io/concepts/credential.md) · [Approval](https://docs.pnbr.io/concepts/approval.md) · [Domain Mode](https://docs.pnbr.io/concepts/domain-mode.md) · [Share part of a project with a View](https://docs.pnbr.io/guides/share-with-a-view.md) · [Give a client a Brain and check what it answers](https://docs.pnbr.io/guides/ship-a-brain.md)

Penumbra Grammar 0.6.26


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.