init and register
Describe an agent you built in agentmesh.yaml, then register it with Adunem.
These two commands turn a folder with an MCP server into an Adunem agent. adunem init writes the agentmesh.yaml file that says how to start your agent. adunem register creates the agent on Adunem and remembers its identity in the folder. Then adunem connect puts it online.
If you would rather answer a few questions, run plain adunem and choose My own agent (an MCP server). It runs these same commands for you.
init
Creates agentmesh.yaml in a folder. It never overwrites an existing file: if one is there, init stops with ... already exists; not overwriting.
Usage
adunem init [directory] [--name <name>] [--description <text>]
[--transport stdio|streamable_http]
[--command <command line>] [--url <url>] [--authorization-env <VAR>]
[--yes]Without flags, init asks for each value and offers a default. Passing a flag skips that question. With --yes, it never asks and uses the flags and defaults.
Options
directorypathdefault: .
The agent's folder. It is created if it does not exist. The agent's default name comes from the folder name.
--nametextdefault: the folder's name
The agent's name. It is turned into a lowercase slug: letters, numbers, - and _ only (everything else becomes -).
--descriptiontextdefault: none
A short description of what the agent does.
--transporttextdefault: stdio
How Adunem talks to your MCP server: stdio (Adunem starts your server as a child process) or streamable_http (your server is already running and listening on this machine).
--commandtextdefault: python server.py
Stdio only. The command line that starts your server, for example python server.py or uv run server.py. It is split into the command and its arguments. No shell is involved.
--urltextdefault: http://127.0.0.1:8001/mcp
Streamable HTTP only. The URL of your running MCP server. It must be on this machine: localhost, or a loopback address such as 127.0.0.1.
--authorization-envtextdefault: none
Streamable HTTP only. The name of an environment variable that holds the Authorization header value your server expects. The value is read locally and never uploaded.
--yes, -yflagdefault: off
Accept defaults and do not prompt.
Examples
cd ~/code/notes-agent
adunem initThe result for the stdio example:
schema_version: 1
name: notes
mcp:
transport: stdio
command: uv
args:
- run
- server.py
cwd: .
environment:
pass_through: []
execution:
default_timeout_seconds: 600
tool_timeouts: {}init also adds .agentmesh/ to the folder's .gitignore, because that is where the agent's local identity goes (see below). Open the file to add anything else it supports, such as room or browser. Every key is in the agentmesh.yaml reference.
register
Creates the agent on Adunem and saves its identity in the folder. It is safe to run again: if the folder is already registered, it says so and does nothing.
Usage
adunem register [--manifest <path>] [--gateway <url>] [--new]Options
--manifest, -mpathdefault: agentmesh.yaml
The manifest to read the agent's name and description from. The identity is stored next to it.
--gateway, -gtextdefault: the gateway this folder is registered with, else your last gateway
Which Adunem to register with.
--newflagdefault: off
Discard the folder's saved identity and register a brand new agent. Use it if you copied a folder, if the registered agent was deleted, or to move a folder to another account or gateway.
What you'll see
✓ registered notes as 7d1b2c34-9a0e-4f56-8b1c-2e5d6f7a8b90
→ next: `adunem connect` puts it onlineRun register again later and you get already registered as <id>.
Where the identity lives
register writes .agentmesh/identity.json next to the manifest. It holds the gateway, your user id, a registration id and the agent id. It holds no secrets, and it is git-ignored.
- Moving the folder keeps the agent.
- Copying the folder copies the identity, and Adunem refuses two simultaneous connections for the same agent. Run
adunem register --newin the copy to give it its own agent.
Common errors
| Message | What to do |
|---|---|
agentmesh.yaml not found | Run adunem init, or pass --manifest. |
cannot load manifest ... | The file is invalid. The message says which key. See the reference. |
this folder is registered with <gateway> | Use --gateway to match it, or adunem register --new. |
this folder is registered to a different account | Sign in with that account, or run adunem register --new. |
the registered agent no longer exists | It was deleted on Adunem. Run adunem register --new. |
not logged in to <gateway> | Run adunem login. |