Agent Manifests
The JSON-on-disk agent manifest format — schema_version, agent DID, allowed_side_effects, the servers array with transport/command/args/env/package_digest/version/tools, and the locked design rules.
An agent manifest is a JSON-on-disk description of what tools a Matrix agent has access to. It is loaded by executor/tool at boot; the canonical Go types live in executor/tool/manifest.go (AgentManifest, ServerEntry, ToolEntry, NativeToolEntry).
Files
| File | Purpose |
|---|---|
agents/default.json | The per-user baseline agent for v1. Starting point for fork-and-customize. |
agents/neo.json | Neo's conversational-agent manifest. |
agents/forge.json | Forge agent manifest. |
Schema
{
"schema_version": 1,
"agent": "matrix://agent/default",
"description": "…",
"allowed_side_effects": ["read", "write", "network", "shell"],
"servers": [
{
"alias": "fs",
"transport": "stdio",
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"],
"env": [],
"package_digest": "sha256:0000…",
"version": "2026.1.14",
"tools": [
{"name": "read_text_file", "description": "Read the contents of a text file", "side_effect_class": "read"},
{"name": "write_file", "description": "Write content to a file", "side_effect_class": "write"}
]
}
]
}Fields
| Field | Meaning |
|---|---|
schema_version | Manifest schema version (currently 1). |
agent | The agent's matrix://agent/<name> DID. |
allowed_side_effects | The side-effect classes this agent may perform (read, write, network, shell). |
servers[].alias | Short name used in tool URIs (matrix://tool/mcp/<alias>/…). |
servers[].transport | stdio or http. |
servers[].command / args | How to spawn a stdio server. |
servers[].env / headers | Credential refs ($env:NAME). |
servers[].version | Server version (forms the tool URI pin). |
servers[].package_digest | sha256 of the published package (sha256:<64-hex>). |
servers[].tools[] | The exhaustive list of tools the server advertises, each with a side_effect_class. |
Locked design rules
| # | Rule |
|---|---|
| Q15 | Transports = stdio + http (streamable HTTP); SSE-only deferred. |
| Q17 | Tool URI scheme: matrix://tool/mcp/<server-alias>/<tool-name>@<version>. |
| Q18 | Credentials via $env:NAME refs in env/headers; never journaled. |
| Q19 | native_tools is the placeholder slot for chain tools (v1.1). |
| Q21 | tools MUST exhaustively enumerate what the server advertises; the manager rejects drift at boot. |
| Q22 | package_digest MUST be the sha256 of the published package. |
The placeholder digests in default.json are zero-filled (sha256:0000…) for bootstrap testing only. Before any production or chain-anchoring deployment, install the pinned package, compute its real sha256, and replace the placeholder.