Skip to main content

Documentation Index

Fetch the complete documentation index at: https://agentvolumes.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

Agent Volumes separates compatibility declarations from dependency constraints. Where dependencies pin version requirements for resolution, compatibility declarations are advisory metadata: they tell discovery systems, tooling, and consumers what execution context your volume was built for. Runtimes, protocols, providers, and environment requirements are all declared this way — they appear in volume.toml and are preserved and surfaced as-is by compliant tooling, which evaluates them only when it explicitly understands the corresponding version scheme.

​
Runtime compatibility ([[runtimes]])

Declare which agent runtimes your volume supports by adding one [[runtimes]] entry per target runtime. If you omit the array entirely, the volume makes no runtime-specific compatibility claim. 
[[runtimes]]
name = "claude-code"
compatibility = "^1.0.0"

[[runtimes]]
name = "opencode"
compatibility = ">=0.1.0"

[[runtimes]]
name = "cursor"
compatibility = ">=1.0.0"
The compatibility field is a required version expression for each runtime entry, not a dependency constraint. Tooling preserves it as authored and only evaluates it when the client explicitly understands the version scheme for that runtime. Unknown-scheme expressions are advisory metadata for discovery, display, diagnostics, and adapter selection — a client must not reject a volume solely because it cannot parse the expression.

​
Recognized runtime identifiers

The v0.1 specification defines 18 runtime identifiers. Adding a new identifier to this list is an additive, non-breaking spec update.
Runtime IDDescription
aiderAider CLI coding agent
claude-codeAnthropic’s Claude Code CLI agent
clineCline IDE and CLI agent
codexOpenAI Codex CLI agent
continueContinue IDE and CLI agent
cursorCursor AI editor
crewaiCrewAI agent framework
geminiGoogle Gemini CLI agent
generic-cliAny CLI-based agent runtime
generic-mcpAny MCP-compatible client
gooseGoose desktop and CLI agent
hermes-agentHermes Agent autonomous runtime
langgraphLangGraph agent runtime SDK
openai-agentsOpenAI Agents SDK
openclawOpenClaw autonomous agent runtime
opencodeOpenCode CLI agent
pi-agentPi coding agent runtime
semantic-kernelMicrosoft Semantic Kernel SDK
Runtime identifiers describe the execution host, not the underlying AI model. claude-code identifies Anthropic’s CLI agent; it says nothing about which model that agent is configured to use. Model/provider compatibility is outside the v0.1 runtime identifier model.

​
Protocol compatibility ([[protocols]])

If your volume exports MCP servers or LSP servers, declare protocol compatibility using the [[protocols]] array. The version field accepts whatever version scheme the protocol ecosystem uses — MCP uses CalVer versions, LSP uses short numeric SemVer-compatible versions. 
[[protocols]]
name = "mcp"
version = ">=2025.02"

[[protocols]]
name = "lsp"
version = ">=3.17"
Protocol IDDescription
mcpModel Context Protocol
lspLanguage Server Protocol
Like runtime compatibility expressions, protocol version expressions are advisory. Tooling must not reject a manifest solely because it cannot evaluate the expression — different protocols use different version schemes, and the baseline treats unknown schemes as metadata.

​
Provider declarations

Providers are external services your volume integrates with. Declare them at the volume level in [volume], at the component level in [[components]], or both. These are discovery and compatibility hints — they are not dependency declarations and do not affect resolution. 
[volume]
schema = 1
name = "research-agent-pack"
version = "1.4.0"
description = "Research assistant with arXiv and Semantic Scholar integration"
license = "Apache-2.0"
role = "plugin"
providers = ["arxiv", "semantic-scholar"]

[[components]]
type = "tool"
name = "arxiv-search"
entrypoint = "./tools/arxiv-search.json"
providers = ["arxiv"]

[[components]]
type = "tool"
name = "scholar-search"
entrypoint = "./tools/scholar-search.json"
providers = ["semantic-scholar"]

​
Common provider identifiers

The spec lists these as common providers. Provider strings are freeform — you can use identifiers outside this list for niche integrations — but using well-known names ensures your volume is discoverable through standard search filters.

Dev platforms

github, gitlab

Communication

slack, discord

Project management

linear, jira, notion

Infrastructure

docker, kubernetes

Cloud

aws, gcp, azure

Data

postgres

AI

openai, anthropic

System surfaces

filesystem, browser

​
Environment requirements ([environment])

Declare execution environment requirements in [environment]. Omitting any field means no restriction for that dimension — the volume is assumed to work in any environment for that dimension. 
[environment]
runtimes = ["node", "bun"]
os = ["linux", "macos", "windows"]
arch = ["x64", "arm64"]

​
Valid values

Language runtimes required to execute the volume’s components:node, bun, deno, python, ruby, go, rust

​
Permissions ([permissions])

Permissions declare the maximum capability surface your volume requires. Volume-level permissions apply to all components. Individual components may declare narrower permissions using a permissions table in their [[components]] entry, but they can never declare broader permissions than the volume permits. 
[permissions]
filesystem = "read"
network = "read"
shell = "deny"
browser = "deny"

​
Permission values

PermissionValid valuesDefault
filesystemdeny, read, write, read-writedeny
networkdeny, read, write, read-writedeny
browserdeny, read, write, read-writedeny
shelldeny, allowdeny
For filesystem, network, and browser, the values map to intent:
  • deny — no access
  • read — inspect, list, search, fetch, or observe without side effects
  • write — create, modify, delete, submit, or otherwise trigger side effects
  • read-write — both read and write behavior permitted
For shell, the v0.1 baseline is coarse: allow or deny.

​
Permission narrowing at the component level

A component may omit a permission field to inherit the volume-level default, or it may declare a value that is narrower than the volume’s setting. The valid narrowing partial order for filesystem, network, and browser is: 
deny < read < read-write
deny < write < read-write
read and write are sibling permissions — neither is narrower than the other. This means:
  • A component under a read-write volume may declare read, write, or deny.
  • A component under a read volume may declare deny, but not write.
  • A component under a write volume may declare deny, but not read.
  • A component under a deny volume may only declare deny (or omit the field).
For shell: deny < allow. A component under a deny volume cannot declare allow.
Permission escalation is a validation failure. If a component declares a permission broader than its parent volume, clients must fail before submission when they detect it. Bibliothecas that discover permission escalation must block the affected artifact from continued distribution.

​
Component-level permission example

[permissions]
filesystem = "read-write"
network = "read"
shell = "deny"
browser = "deny"

[[components]]
type = "tool"
name = "read-only-scanner"
entrypoint = "./tools/scanner.json"
description = "Read-only file scanner — needs only read access"

# This component narrows filesystem from "read-write" to "read"
[components.permissions]
filesystem = "read"

[[components]]
type = "tool"
name = "file-writer"
entrypoint = "./tools/writer.json"
description = "Writes output files — needs write access"
# Inherits filesystem = "read-write" from volume

​
Complete compatibility example

The following manifest shows all compatibility declarations together: 
[volume]
schema = 1
name = "research-agent-pack"
version = "1.4.0"
description = "Research assistant plugin with literature analysis tools"
license = "Apache-2.0"
role = "plugin"
secondary-roles = ["provider"]
providers = ["arxiv", "semantic-scholar"]

[publisher]
id = "example"

[[components]]
type = "agent"
name = "literature-reviewer"
entrypoint = "./agents/literature-reviewer/AGENT.md"
description = "Autonomous literature review agent"

[[components]]
type = "mcp-server"
name = "research-mcp"
entrypoint = "./.mcp.json"
description = "MCP server providing research tool endpoints"

# Runtime compatibility
[[runtimes]]
name = "claude-code"
compatibility = "^1.0.0"

[[runtimes]]
name = "opencode"
compatibility = ">=0.1.0"

# Protocol compatibility
[[protocols]]
name = "mcp"
version = ">=2025.02"

# Permissions
[permissions]
filesystem = "read"
network = "read"
shell = "deny"
browser = "deny"

# Environment
[environment]
runtimes = ["node", "bun"]
os = ["linux", "macos", "windows"]