# Packages

> Export an agent or its components as a Raw package, pack it into a .rawpkg archive, install it on another machine, and bind it to a local model.

A Raw package bundles an agent and the components it uses, such as tools, skills, hooks, variables, and MCP server definitions. You can share a package as a `.rawpkg` file. The recipient installs it, then binds an agent in their own config to their own model.

Installing a package does not start a model, run a tool, run a hook, or connect to an MCP server. Nothing in a package runs until an agent selects it.

## Terms

| Term           | Meaning                                                                                                   |
| -------------- | --------------------------------------------------------------------------------------------------------- |
| Package folder | A directory with a `raw-package.json` manifest and the files it declares. This is the editable source.    |
| `.rawpkg`      | A ZIP archive of a package folder, with a checksum for each file. This is the shareable artifact.         |
| Alias          | The local name you give an installed package, such as `kit`. Agents refer to components as `pkg/kit/...`. |
| Binding        | An agent in your config that points at a package agent, with your model and input values.                 |

## The manifest

`raw-package.json` lists every file the package uses, and the components it exports.

```json
{
  "schema_version": 1,
  "name": "@example/research-kit",
  "version": "1.0.0",
  "description": "A reusable research agent and its components",
  "files": [
    "agents/researcher.json",
    "prompts/researcher.md",
    "skills/review",
    "tools/search",
    "mcp/search.json"
  ],
  "exports": {
    "agents": { "researcher": "agents/researcher.json" },
    "skills": { "review": "skills/review" },
    "tools": { "search": "tools/search" },
    "mcp": { "search": "mcp/search.json" }
  },
  "inputs": {
    "type": "object",
    "properties": {
      "region": { "type": "string", "default": "Hanoi" }
    },
    "required": []
  },
  "requires": ["raw.tool-api/2"],
  "dependencies": {}
}
```

| Field            | Rule                                                                                                                                                              |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `schema_version` | Must be `1`.                                                                                                                                                      |
| `name`           | A scoped name, `@owner/name`.                                                                                                                                     |
| `version`        | A SemVer version, such as `1.0.0`.                                                                                                                                |
| `files`          | Every file or folder the package uses. Anything not listed is not included in the archive.                                                                        |
| `exports`        | Named components by category: `agents`, `skills`, `tools`, `vars`, `var_providers`, `mcp`, and `hooks`. Each export points at a file or folder listed in `files`. |
| `inputs`         | Values the recipient supplies when binding. Each property can have a `type`, `enum`, `default`, and `x-raw-kind`.                                                 |
| `requires`       | The host capabilities the package needs, such as `raw.tool-api/2`.                                                                                                |
| `dependencies`   | Other packages this one uses, each pinned to an exact archive. Raw does not fetch dependencies.                                                                   |

An agent definition inside a package does not name a model. The recipient chooses the model when binding.

### Recipient inputs

An input is a value the recipient supplies. The package marks where it is used with a whole value: `{"$input": "region"}`. The `x-raw-kind` field tells Raw how to treat the value:

| Kind         | Meaning                                                         |
| ------------ | --------------------------------------------------------------- |
| `file`       | A path. It resolves from the recipient’s config directory.      |
| `directory`  | A directory path.                                               |
| `env-name`   | The name of an environment variable on the recipient’s machine. |
| `var-source` | A variable source definition.                                   |

## Create and share a package

1. Export a configured agent as a package folder. The export copies the agent’s prompt and the files its components use. It reports which inputs the recipient must supply.

   ```sh
   raw package export --agent researcher --name @example/research-kit --version 1.0.0 --out ./research-kit
   ```

2. Check the folder without running any of its code.

   ```sh
   raw package validate ./research-kit
   raw package inspect ./research-kit
   ```

3. Pack the folder into a `.rawpkg` archive.

   ```sh
   raw package pack ./research-kit --out research-kit-1.0.0.rawpkg
   ```

4. Send the archive through any file channel. Raw does not download packages from the internet.

By default, export turns literal variable values, and file, provider, and MCP paths, into recipient inputs. Two options change this. `includeLiterals` and `includeFiles` are library options. The dashboard exposes both as checkboxes. Use them only for values you are sure can be shared.

> **Caution:**
>
> Do not include credentials, your absolute paths, or your session history in a package. Export does not copy your session database, but it does copy any literal values you choose to include.

## Install and bind a package

1. Install the archive under an alias.

   ```sh
   raw package install research-kit-1.0.0.rawpkg --as kit
   ```

   Installing the same archive again under the same alias has no effect. To replace an alias with a different archive, use `raw package update`.

2. Bind an agent to a model in your config. The binding can also take input values from a JSON file.

   ```sh
   raw agent add researcher --from pkg/kit/agents/researcher --model local --inputs inputs.json
   ```

   This writes an agent to your config. The package stays as data.

3. Run the agent as usual.

   ```sh
   raw --agent researcher "Summarize the open questions in the notes"
   ```

The binding in your config looks like this:

```json
{
  "agents": {
    "researcher": {
      "from": "pkg/kit/agents/researcher",
      "model": "local",
      "inputs": { "region": "Hanoi" },
      "overrides": { "max_steps": 30 }
    }
  }
}
```

`overrides` replaces a field of the package agent. Lists and blocks, such as `tools` or `skills`, are replaced in full, not merged.

### Use a package component without a package agent

An agent you wrote yourself can select components from an installed package:

```json
"tools": {
  "use": [
    "builtin/read_file",
    { "ref": "pkg/kit/tools/search", "as": "web_search" }
  ]
}
```

The `as` name is the name the model sees. The policy rules still match the component’s real identity.

## Manage installed packages

| Command                                | What it does                                                                       |
| -------------------------------------- | ---------------------------------------------------------------------------------- |
| `raw package list`                     | Lists installed aliases.                                                           |
| `raw package install PATH --as ALIAS`  | Installs a `.rawpkg` file or a package folder under an alias.                      |
| `raw package update ALIAS --from PATH` | Replaces an alias with a new archive or folder. The next run uses the new version. |
| `raw package link DIR --as ALIAS`      | Registers an editable folder. Each new run uses the folder’s current contents.     |
| `raw package fork ALIAS --out DIR`     | Copies an installed package into an editable folder.                               |
| `raw package remove ALIAS`             | Removes an alias. Refused while an agent still refers to it.                       |

Each command prints JSON to stdout. Package commands take `--config PATH` to choose which config’s installation record they update, and they do not open your session database.

### Update and roll back

- To update, run `raw package update` with the new archive. Agents that were bound to the package pick up the change on their next run. Saved conversations resume with the same ID.
- To roll back, update the alias with the previous archive.
- For development, fork the package to a folder, edit it, and link the folder under a new alias. Each new run snapshots the folder’s current files.

> **Note:**
>
> Changing only the version label does not change the agent. Changes to the effective prompt, schemas, or helper code are what take effect as a runtime change.

## Browser workflow

The dashboard has the same package features under **Library → Packages**. See the [dashboard guide](https://raw.tlelabs.com/docs/guides/dashboard/).

## Related

- [Configuration reference](https://raw.tlelabs.com/docs/reference/configuration/) lists the binding fields.
- [Tools](https://raw.tlelabs.com/docs/extend/tools/) and [Skills](https://raw.tlelabs.com/docs/extend/skills/) describe the components a package can export.
- The [examples](https://github.com/lploc94/raw-cli/tree/main/examples/packages) include a mixed kit, a tool-only package, and a skill-only package.