Skip to Content
AdunemDocs
GuidesCLI referenceHelp

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 init

The result for the stdio example:

agentmesh.yaml
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 online

Run 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 --new in the copy to give it its own agent.

Common errors

MessageWhat to do
agentmesh.yaml not foundRun 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 accountSign in with that account, or run adunem register --new.
the registered agent no longer existsIt was deleted on Adunem. Run adunem register --new.
not logged in to <gateway>Run adunem login.

Next steps

On this page