Reproducible agent stacks.
An open specification for agent components on disk: the harness, its plugins, and the runtimes they depend on, as a single unit that runs the same way on every machine.
Why Agent Stacks?
An agent is not one program. It is a harness, a set of skills, some MCP servers, a handful of prompts and settings, and implied dependencies. Today those are ad-hoc. "The same agent" could be something different on every machine.
We believe agents should be:
- Inspectable. Agent parts should be easy to identify.
- Composable. Agent parts should be easy to change.
- Reproducible. Agents should run the same on every machine.
A stack on disk
A plugin is a directory laid out as Agent Plugins.
A stack installs its plugins under
share/agent-plugins/, one directory each, and provides one launcher script at
bin/<stack-name>.
agent-stack-claude-code/
├── bin/claude-code # the launcher for the stack
└── share/agent-plugins/
├── caveman/ # plugin
│ ├── plugin.json
│ ├── skills/caveman-compress/scripts/compress.py
│ └── bin/python3 # the runtime for compress.py
└── agentmemory/ # plugin
├── plugin.json
├── mcp.json
├── skills/
└── bin/npx # the runtime for mcp.json's command
See the specification. A Nix
build, a Debian package, a Homebrew formula, or a tarball unpacked into /usr/local can
all satisfy the specification. Any conforming harness reads the same tree.
A meta specification
Agent Stacks are deliberately minimal interpretations of existing specifications. For parts where widely adopted standards do not exist yet, agent-stacks is creating neutral on-disk formats.
| Standard | Organization | What we add |
|---|---|---|
| Agent Plugins | agent-plugins.org | The plugin package: manifest, layout, mcp.json |
| Agent Skills | agentskills.io | What a skill is: SKILL.md and what sits beside it |
| MCP | Agentic AI Foundation | Wire behavior of the servers a plugin ships |
| Agent Stacks | agent-stacks.org | Which versions, where plugins go, dependencies, the on-disk layout |
| Sandbox | agent-stacks.org | An on-disk portable representation of a sandbox |
| Harness | agent-stacks.org | An on-disk portable representation of a harness |
Launching a stack
- On disk Portable format share/agent-plugins/
- Invoke Launcher bin/claude-code
- Just in time Runtime format harness and sandbox config
- Run Running agent stack harness, plugins, sandbox
Try a reference implementation
nix run github:agent-stacks/claude-code
The command above puts one directory on your machine with all of the parts, then launches the agent stack.
agent-pkgs is a Nix package set implementing the layout: skills and MCP server configurations packaged as reproducible, closure-complete packages and composed into stacks. It builds with plain Nix.
An organization can fork it as an internal plugin marketplace: keep the library functions, replace the package set with your own, and ordinary CI builds every package on every pull request. Nix is the first implementation. We invite additional implementations.
Where to start
I use a harness every day
You can use Agent Stacks to manage the configuration of your existing harness (Claude Code, Codex, Pi).
Developer quick start →I manage agents for a team
You can use Agent Stacks to define the harness and plugins for a team and keep them current.
Create an agent stack →I write skills or MCP servers
You can use Agent Stacks to package skills or MCP servers together with their dependencies, so they run the same everywhere.
Create an agent plugin →What's on the roadmap?
The Agent Stacks spec is in active development. It currently supports plugins, harnesses, and commands, with new features coming soon.
We are looking for contributors, especially for native support in more package managers and more harnesses. See open development for how to get involved.
Open development
Agent Stacks is developed in public. Flox is the initial sponsor and wrote the first implementation, and we are looking for contributors and collaborators. We are not attached to any particular technology. The specification is a layout on disk; Nix is just one way to produce it.
If you are packaging agent tooling already, or you maintain a harness that has to load components, we are open to collaborating.