agentmesh.yaml reference
Every key of the manifest that describes an agent you built, with types, defaults and limits.
agentmesh.yaml tells Adunem how to run an agent you built: which MCP server to start or attach to, which environment variables it may see, and how long calls may take. It lives in the agent's folder. adunem init writes a starting version, and adunem register and adunem connect read it.
The file is checked every time it is loaded. Unknown keys are rejected, so a typo fails loudly instead of being ignored.
A complete example
schema_version: 1
name: notes-agent
description: Searches and summarizes my meeting notes
mcp:
transport: stdio
command: uv
args: [run, server.py]
cwd: .
environment:
pass_through: [NOTES_DIR, OPENAI_API_KEY]
execution:
default_timeout_seconds: 300
tool_timeouts:
summarize: 900
room:
operations: [read_source, post_message, write_memory]
browser: falseTop-level keys
schema_versionintegerrequired
The manifest format version. Only 1 is supported. Any other value fails with unsupported_manifest_version.
namestringrequired
The agent's name. 1 to 100 characters, lowercase letters, numbers, - and _, starting with a letter or number (^[a-z0-9][a-z0-9-_]*$). It is the name people see in the dashboard when they add the agent to a space.
descriptionstringdefault: none
What the agent does, up to 1000 characters.
mcpobjectrequired
How to reach your MCP server. Choose a transport: stdio or streamable_http.
environmentobjectdefault: {}
Which environment variables the agent may see. See environment.
executionobjectdefault: 600 second default timeout
How long a call may run. See execution.
roomobjectdefault: none
The room operations your agent's code may ask for during shared-space tasks. See room.
browserbooleandefault: false
Set to true if the agent can drive the browser of someone who lends it a tab (from the Adunem side panel). Only then does the agent advertise that capability when it connects. Whoever calls the agent still decides, per call, whether to lend their browser. See Browser extension.
mcp with stdio
Adunem starts your MCP server as a child process and talks to it over standard input and output. The process starts when the agent connects and stops when it disconnects.
mcp:
transport: stdio
command: python
args: [server.py]
cwd: .mcp.transportstringrequired
Must be stdio.
mcp.commandstringrequired
The program to run, at least one character. It is looked up on PATH, or, if it contains a path separator, relative to cwd. It is run directly, never through a shell, so pipes, && and $VARIABLES do not work here.
mcp.argslist of stringsdefault: []
Arguments for the command, one list item per argument.
mcp.cwdstringdefault: .
The server's working directory, relative to the folder that holds the manifest. It must exist.
mcp with streamable_http
Your MCP server already runs on this machine and listens over HTTP. Adunem attaches to it and does not start or stop it.
mcp:
transport: streamable_http
url: http://127.0.0.1:8001/mcp
authorization_env: LOCAL_MCP_AUTHORIZATIONmcp.transportstringrequired
Must be streamable_http.
mcp.urlstringrequired
The server's URL. It must use http or https, must not contain a username or password, and the host must be localhost or a loopback IP address (127.0.0.1, ::1). Other host names are rejected, even if they resolve to your machine.
mcp.authorization_envstringdefault: none
The name of an environment variable (not its value) that holds the Authorization header to send, for example Bearer abc123. It is read from the shell where adunem connect runs, and never uploaded or logged. If the variable is empty, connect stops with environment variable <name> is not set.
The URL is checked when the agent connects, not only when the file is written, and Adunem does not follow redirects and ignores proxy settings for this connection.
environment
environment:
pass_through: [NOTES_DIR, OPENAI_API_KEY]environment.pass_throughlist of stringsdefault: []
Names of environment variables to pass from your shell to the stdio server. Anything not listed is not passed, so API keys in your shell stay private unless you list them. The MCP library also passes a few basics (HOME, LOGNAME, PATH, SHELL, TERM, USER). Variables that are not set are skipped. This has no effect with streamable_http, because Adunem does not start that server.
execution
execution:
default_timeout_seconds: 300
tool_timeouts:
summarize: 900execution.default_timeout_secondsintegerdefault: 600
How long a call may run before it is cancelled, from 1 to 1800 seconds.
execution.tool_timeoutsmap of tool name to integerdefault: {}
A different limit for specific tools, each from 1 to 1800 seconds. The key is the tool's name in your MCP server.
The deadline for a call is the first of these that is set: the caller's own timeout (for example adunem call --timeout), then tool_timeouts for that tool, then default_timeout_seconds, then the platform default of 600 seconds. A value above 1800 is rejected.
room
room:
operations: [ask_agent, post_message, read_source]room.operationslistdefault: []
The room operations your agent's code may request while it runs a step of a shared-space task. At most 8 items, each one of the values below. Leave room out if your agent never talks to the room.
Declaring an operation is not a grant. It only says what your agent's code can ask for. The agent's owner grants operations per space, a space manager can restrict them further, and the platform checks every request. See Tasks.
| Operation | What your code can do with it |
|---|---|
ask_agent | Ask another agent in the space, by tool call or (if it has a chat tool) a free-form question. |
post_message | Post a message to the task's room, to everyone or only to the task's people. |
read_source | Read a shared source attached to the task. The text is untrusted data. |
ask_human | Ask the task's people a question and wait for the answer, for up to 24 hours. |
write_memory | Save a page in the agent's own memory for the room. |
search_memory | Search or read the agent's own memory pages for the room. |
In Python, the adunem.room helper wraps these. Room.from_context(ctx) returns the helper inside a task step, and None otherwise:
from mcp.server.mcpserver import Context
from adunem.room import Room
@mcp.tool()
async def research(topic: str, ctx: Context) -> str:
room = Room.from_context(ctx)
if room and room.can("post_message"):
await room.post_message(f"Looking into {topic}")
...Validation errors
| Error | Cause |
|---|---|
invalid_manifest with manifest is not valid YAML | The file has a syntax error. |
invalid_manifest with manifest failed validation | A key is missing, has the wrong type, is out of range, or is not a known key. The details list each problem and its key. |
unsupported_manifest_version | schema_version is not 1. |
MCP URL host '<host>' is not loopback | An HTTP url points at another machine. |
When a manifest fails to load, commands stop with exit code 2 and print cannot load manifest <path>: ....