volume.toml file at its root. This file is the normative human-authoring format for package metadata: it declares who published the volume, what components it exports, which runtimes it targets, what permissions it needs, and which other volumes it depends on. Tooling validates manifests against a canonical parsed-data model derived from the TOML source, so the structure you write here is the source of truth for everything downstream — resolution, installation, trust, and discovery.
Schema version
The[volume] table must include schema, set to the integer 1. Key order is not semantically significant. Tooling rejects manifests with unrecognized schema versions.
[volume] table
The [volume] table carries package identity and discovery metadata.
Required fields
integer
required
Manifest schema version. Currently
1.string
required
Volume identifier. Use a bare name for scopeless volumes (
my-agent) or @scope/name for scoped
volumes (@acme/research-pack). Name segments must be lowercase alphanumeric with hyphens, 1–128
characters, not starting or ending with a hyphen, and without consecutive hyphens. Scoped
identifiers also include a scope segment up to 64 characters, so the full scoped volume.name can
be longer than a bare name.string
required
SemVer 2.0.0 version string (e.g.,
1.4.0).string
required
One-line summary of the volume. Maximum 256 characters.
string
required
SPDX license expression (e.g.,
Apache-2.0, MIT, Apache-2.0 OR MIT).string
required
Primary package role. One of:
component, plugin, provider, meta. See Package
roles for guidance on choosing the right role.Optional fields
string
URL to the volume’s homepage or documentation site.
string
URL to the source repository.
string
URL to extended documentation.
string[]
Freeform keywords for search discovery (e.g.,
["research", "arxiv", "academic"]).string[]
Additional package roles layered on top of the primary role (e.g.,
["provider"]).string[]
External services the volume integrates with at the volume level (e.g.,
["github", "slack"]).
These are discovery hints, not dependency declarations. See
Compatibility for common provider examples and naming
guidance.[publisher] table
The [publisher] table is required in every volume.toml, including scoped volumes and role = "meta" volumes. It identifies the publisher entity, not their verification status — verification is managed by the bibliotheca.
string
required
Publisher identifier. For scopeless volumes, identifies the owner of the volume name. For scoped
volumes, identifies the owning scope (without the
@ prefix).[[components]] array
Declare every component the volume exports as an array of TOML tables. A component without a corresponding [[components]] entry is not exported, even if its entrypoint file exists in the volume.
Required fields per component
string
required
Component type. One of:
agent, skill, command, tool, hook, mcp-server, lsp-server.string
required
Component name. Lowercase alphanumeric with hyphens. Must be unique within the volume across all
component types.
string
required
Relative path from the volume root to the component’s primary entry file (e.g.,
./skills/summarize-paper/SKILL.md). Must not be absolute, must not contain .. segments, and
must resolve to a regular file.Optional fields per component
string
One-line description of the component.
string[]
External services integrated by this specific component.
object
Component-specific permission overrides. Values must be narrower than or equal to the parent
volume’s permissions — you cannot escalate permissions at the component level.
Component names must be unique across all component types within a volume. You cannot have a
skill named search and a tool named search in the same volume.[dependencies] table
Declare volume-level dependencies as a TOML table where each key is a volume name and each value is a SemVer constraint string. See Dependencies for the full constraint grammar.
[[external-dependencies]] array
Declare package dependencies outside the Agent Volumes pkg:volume ecosystem as audit metadata. These records are used for review, policy, BOM export, and potential-exposure diagnostics. They are not resolver inputs, lockfile entries, installed package evidence, scanner findings, VEX status, or confirmed vulnerability evidence.
string
required
Package URL for an external ecosystem package. It must not use the
volume purl type and must not
include a PURL version component or subpath. Put version intent in constraint.string
required
VERS expression for the external package range. This is not the Agent Volumes SemVer dependency
grammar.
string
required
Dependency use context. Core values are
runtime, build, development, test, optional,
peer, source, documentation, and other. Extension values use reverse-DNS namespace syntax,
such as org.example:codegen.string[]
Optional component scope. When present, the array must be non-empty, duplicate-free, and contain
only component names declared in the same manifest. Omit it for volume-wide external dependency
declarations.
[component-dependencies] table
Declare which components in this volume depend on specific components from other volumes. Each key is the name of a component declared in this manifest’s [[components]] array; each value is an array of component purl strings.
A component-level dependency implies the parent volume dependency. After volume resolution,
tooling verifies that the referenced components exist in the resolved volume version.
[[runtimes]] array
Declare which agent runtimes your volume is compatible with. Each entry names a runtime and provides a compatibility version expression.
string
required
Runtime identifier. See Compatibility for the full list
of 18 recognized runtime IDs.
string
required
Required advisory version expression for the runtime. This is metadata for discovery and
diagnostics — not a hard dependency constraint. Tooling preserves the expression as authored and
only evaluates it when the runtime’s version scheme is explicitly understood.
[[runtimes]] array entirely, the volume makes no runtime-specific compatibility claim.
[[protocols]] array
Declare protocol compatibility for volumes that export MCP servers or LSP servers.
string
required
Protocol identifier. One of:
mcp, lsp.string
required
Required protocol version expression. Protocol ecosystems use different version schemes
(date-like, short numeric, SemVer-compatible), so this is advisory metadata. Tooling must not
reject a manifest solely because it cannot evaluate the expression.
[permissions] table
Declare the maximum permissions your volume needs. All components inherit these defaults; individual components may declare narrower (but never broader) permissions.
string
default:"deny"
Local filesystem access. One of:
deny, read, write, read-write.string
default:"deny"
Network access. One of:
deny, read, write, read-write.string
default:"deny"
Browser access. One of:
deny, read, write, read-write.string
default:"deny"
Shell command execution. One of:
deny, allow.[environment] table
Declare execution environment requirements. Omitting any field means no restriction for that dimension.
string[]
Required language runtimes. Valid values:
node, bun, deno, python, ruby, go, rust.string[]
Target operating systems. Valid values:
linux, macos, windows.string[]
Target CPU architectures. Valid values:
x64, arm64, x86.