Packages

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.

{
  "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.

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.
Terminal window
```
raw package export --agent researcher --name @example/research-kit --version 1.0.0 --out ./research-kit
```

Check the folder without running any of its code.

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

Pack the folder into a .rawpkg archive.

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

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.

Install and bind a package

Install the archive under an alias.
Terminal window
```
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.
Bind an agent to a model in your config. The binding can also take input values from a JSON file.
Terminal window
```
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.

Run the agent as usual.

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

The binding in your config looks like this:

{
  "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:

"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.

Browser workflow

The dashboard has the same package features under Library → Packages. See the dashboard guide.

Configuration reference lists the binding fields.
Tools and Skills describe the components a package can export.
The examples include a mixed kit, a tool-only package, and a skill-only package.