Create a bag

Use this when you want to give your agents a capability of your own: a tool that calls your service, a store, or a policy your team shares. A bag is a directory with a bag.yaml manifest, and Barry builds it, registers it, and packs it onto an identity. This guide builds the smallest working bag, hello, with one tool.

Before you begin

Build a Barry. The commands act as the bonanza identity from that guide; use your own identity’s command in its place.
Install Node.js 26, version 26.9 or later, and pnpm 12, the versions Barry’s package.json requires. Barry bundles a bag’s TypeScript with its own build, so you don’t compile anything yourself.
Know where your Barry clone lives, and build its packages once. The SDK, @barry-rocks/sdk, ships in that clone’s sdk directory, and a bag depends on it through a link: path. The SDK’s package resolves to its built dist/ directory, which git doesn’t track, so a fresh clone has nothing to link until you run pnpm build:packages in it.

Create the bag directory

You can scaffold a directory with barry new hello. It writes a bag.yaml with version, name, and description, empty mcp-servers, traits, and tools keys, and a commented-out dependencies example, plus an empty skills/ directory. It writes no package.json and no tools.ts. Don’t pass --server: that option writes a server.ts in an older style, plus a server: key that the manifest parser rejects. The rest of this guide creates every file by hand, so either start from the scaffold or from an empty directory named hello. The commands assume the bag lives at ~/repos/hello, beside your Barry clone.

Write the manifest

The manifest names the bag and says what it provides. name and description are the only required keys:

name: hello
description: Says hello, as an example of a bag with one tool.

The bag’s name becomes its automatic trait and the namespace of its tools. The schema is strict: an unknown key fails the whole manifest, and a bag with a failed manifest contributes nothing. The bag.yaml reference lists every key.

Declare the dependencies

The bag needs the SDK and zod. Point the SDK dependency at the sdk directory of your Barry clone; this file assumes the clone sits beside the bag:

{
  "name": "hello-bag",
  "private": true,
  "type": "module",
  "dependencies": {
    "@barry-rocks/sdk": "link:../barry/sdk",
    "zod": "4.4.3"
  }
}

Pin exact versions. Barry builds the bag from its own directory and its own node_modules, so a package the bag imports and doesn’t declare fails the build.

Write the tools in tools.ts

Barry finds a bag’s tools by convention: it loads tools.ts at the bag’s root, or src/tools.ts when the root has none, and registers every tool the module exports. The manifest never names the file.

import { Barry } from "@barry-rocks/sdk";
import { z } from "zod";

export const greet = Barry.Tool({
  namespace: "hello",
  name: "greet",
  access: "read",
  description: "Greet someone by name.",
  schema: { name: z.string().describe("Who to greet") },
  handler: async ({ name }) => ({ greeting: `Hello, ${name}!` }),
});

Keep a tool’s namespace equal to the bag’s name, so the bag’s automatic trait grants it. The next guide, Write a tool, covers every field.

Check, install, pack, and grant the bag

To validate the bag without installing it, run:
Terminal
```
barry bag check ~/repos/hello
```
The command checks the manifest, the files it names, the bag’s skills, and its actions. Add --deep to also start the tools entry and list the tools it registers; that option runs the bag’s code.
To build the bag and register it on this machine, run:
Terminal
```
barry install ~/repos/hello
```
Barry runs pnpm install in the bag when its dependencies are missing, builds it, and restarts its tool host so new sessions see the tools.
To add the bag to your identity, run:
Terminal
```
bonanza pack hello
```
Packing adds the bag to the identity’s identity.yaml, registers the bag’s traits, and creates any identity-owned stores the bag declares.
To grant the bag’s tools to the identity itself, run:
Terminal
```
bonanza identity traits add hello
```
bonanza tool runs a tool only when the identity’s own grants include it, the same check a session’s tools pass. Packing alone grants nothing under the default bag_grant: session, so the identity needs the bag’s automatic trait, hello, among its default traits. Every guide in this section packs its bag and adds its trait this way before it calls a tool from the terminal.

When you change the bag’s code, run barry install ~/repos/hello again to rebuild it.

Verify

To call the tool from the terminal, run:

bonanza tool hello greet Ada

The command prints the tool’s result, a JSON object with a greeting of Hello, Ada!. To see the bag and the traits it provides, run barry bag show hello; the traits include hello and hello:read.

A session gets the identity’s default traits, so a new session started with bonanza session start has the tool too. Ask the agent to greet someone. To keep the tool out of sessions that don’t ask for it, run bonanza identity traits remove hello and select the trait per session with bonanza session start --traits hello.

If it fails

barry bag check reports a manifest error. Read the key it names. The usual causes are a misspelled key, a key from an older manifest format, and a server: key from barry new --server.
The install says the build failed. The bag imports a package its package.json doesn’t declare, or the SDK link points at the wrong directory. Fix it and run the install again.
bonanza tool says tool access denied: hello:greet. The identity’s grants don’t include the tool. Pack the bag and add its trait, as step 4 shows.
The tool is missing from a session. Start the session with the bag’s trait, and check the tool’s namespace matches the bag’s name. See Troubleshooting.

What’s next

Write a tool for secrets, results, and output schemas.
Add a store to keep data in SQLite.
Test a bag to call your tools from vitest.
Packing bags for installing bags other people wrote.