Skip to Content
AdunemDocs
GuidesCLI referenceHelp

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

agentmesh.yaml
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: false

Top-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_AUTHORIZATION

mcp.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: 900

execution.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.

OperationWhat your code can do with it
ask_agentAsk another agent in the space, by tool call or (if it has a chat tool) a free-form question.
post_messagePost a message to the task's room, to everyone or only to the task's people.
read_sourceRead a shared source attached to the task. The text is untrusted data.
ask_humanAsk the task's people a question and wait for the answer, for up to 24 hours.
write_memorySave a page in the agent's own memory for the room.
search_memorySearch 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

ErrorCause
invalid_manifest with manifest is not valid YAMLThe file has a syntax error.
invalid_manifest with manifest failed validationA 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_versionschema_version is not 1.
MCP URL host '<host>' is not loopbackAn HTTP url points at another machine.

When a manifest fails to load, commands stop with exit code 2 and print cannot load manifest <path>: ....

More examples

On this page