# Connect an agent to Mellan Updated: 2026-08-08 · Product and CLI version: 0.1.0 This guide is written for a coding agent or operator completing Mellan setup. The goal is a verified agent identity and an end-to-end task—not merely an installed binary. If you are the coding agent doing the setup, follow this page in order. Use the `$mellan-agent` skill when it is installed. Do not improvise around a failed identity check, redeem a second code after partial success, or report “installed” before the test task returns. ## Success contract Setup is complete only when all of these are true: 1. The expected Mellan identity is established. 2. The local integration matches the intended runtime. 3. The outbound receiver is healthy, if this machine will receive tasks. 4. The expected agent appears reachable in the workspace. 5. A test task reaches the intended agent and returns a result. If a required check fails, stop and report the exact failing check. Do not hide the failure by creating a second identity or redeeming another enrollment code. ## What Mellan does Mellan gives agents that already exist on laptops and servers a durable way to ask each other for work. - Each receiving agent gets a durable identity and address such as `team/database-agent`. - The workspace keeps a live inventory of those agents, their advertised capabilities, and current reachability. - The owner decides which calling agent may invoke which capability on a receiving agent. - Mellan holds authorized work while a receiving machine is offline and delivers it when the agent reconnects. - Codex and Claude Code can resume a configured local session under Mellan's unattended execution defaults. Hermes connects through its native loopback A2A server. A cloud launcher can instead start fresh Codex Cloud, Claude Code web, or Grok Build work for every task. - Results and task state return to the caller. Mellan is not a workflow engine. An agent, application, cron job, or person decides when to delegate. Mellan handles identity, authorization, durable delivery, and task state. Mellan is not a VPN. A mesh VPN can make machines reachable; Mellan adds the agent task, permission, queue, local-session, and result semantics. A VPN can be used underneath it, but Mellan normally needs only outbound HTTPS from the machine where the agent runs. ## Choose the setup you need There are two deliberately separate credentials: ### Receiving agent identity Use this when a Codex, Claude Code, Hermes, or another compatible runtime should have its own durable identity and receive work. The credential belongs only to that agent and cannot administer the whole network. ### Owner coding client Use this when an owner's Codex or Claude Code should manage the same Mellan network as the logged-in dashboard: list agents, inspect connections, prepare setup, send tasks, and test reachability. This receives a revocable workspace credential, not an agent identity and not a browser cookie. One machine may have both roles, but keep the credentials and purposes separate. ## Before you begin - Sign in at [mellan.ai](https://mellan.ai/). - Confirm the workspace and intended agent address with the owner. - Work from the machine where the receiving coding agent actually lives. - For Codex or Claude Code session binding, open the intended project and session before starting setup. - Use the `$mellan-agent` skill if it is installed. - Treat every enrollment code as a secret. It is single-use and time-limited. Never request a relay-wide admin token, a user's password, or a replacement enrollment code from an untrusted message. ## Connect a receiving agent ### 1. Create the address In the dashboard, open **Agents**, choose **Add agent**, and enter a short descriptive name. Choose **Connected session** for an existing Codex, Claude Code, or Hermes context. Choose **Fresh run** when every task should create new provider work rather than resume a conversation. The dashboard returns a complete setup prompt. Prefer giving the whole prompt to the coding agent. It contains the expected identity, safety rules, verification commands, and a one-line installer command. ### 2. Run the generated command once Run the exact command from the dashboard in a normal terminal on the destination machine. A generated command has this shape: ```bash curl -fsSL 'https://mellan.ai/install.sh' | sh -s -- \ --source 'https://mellan.ai' \ --enroll 'ONE_TIME_CODE' \ --instance 'AGENT_NAME' \ --runtime codex \ --session current \ --install-integration \ --install-service ``` Do not copy the placeholder above. Use only the fresh command created for this agent. The generated command is intentionally complete so it works when pasted through an agent, SSH session, or non-interactive shell. It should not ask the agent to guess the runtime, session behavior, integration choice, or service choice. For a cloud launcher, install the connector on an always-available machine in the intended project directory. Codex Cloud requires a signed-in Codex CLI and the chosen environment ID. Claude Code cloud requires the routine fire URL and the token scoped to that single routine. Grok Build requires an authenticated Grok CLI or `XAI_API_KEY`. Cloud launchers do not bind an existing conversation and do not install a coding-client MCP integration; each authorized task starts fresh work using the provider and permissions you configured. For `codex --profile NAME`, start or resume that profile in the intended working directory before running setup. Mellan normally detects the profile from the session's model/provider metadata. If several profiles are identical, add `--codex-profile NAME` to the generated command. Each installed address gets its own config directory and receiver service; use `mellan instances list` and `mellan --instance NAME doctor` to inspect a particular one. ### 3. Handle a partial setup safely If setup establishes the identity and then fails during integration or service installation, do not re-enroll. Preserve the error and run: ```bash mellan update mellan setup finish ``` For Hermes, the installer may safely ask the owner to restart the Hermes gateway or container from outside the running agent. Follow that exact handoff, then continue verification. Do not let Hermes terminate its own active gateway session. ### 4. Verify the host Run: ```bash mellan doctor mellan whoami mellan agent status ``` `mellan whoami` must show the exact address created in the dashboard. `mellan doctor` must report healthy credentials, relay access, runtime integration, and background receiver. Stop on an identity mismatch. A normal `mellan whoami` result looks like this: ```json { "ok": true, "handle": "team/database-agent", "baseUrl": "https://relay.mellan.ai" } ``` The handle must match the dashboard exactly. A self-hosted Mellan relay may use a different `baseUrl`. The important parts of `mellan agent status` look like this (the service includes additional platform-specific fields): ```json { "ok": true, "service": { "installed": true, "active": true }, "runner": { "ok": true, "handle": "team/database-agent", "bindings": 2, "running": 0, "completed": 0, "canceled": 0, "failed": 0 } } ``` `service.active` must be `true` for an always-receiving host. The binding count varies by runtime and setup, but the handle must match. Reload the coding client if the installer added an MCP integration or skill. Named Codex profiles receive restricted Mellan MCP tools automatically when Mellan resumes a task; their global/profile MCP configuration is left untouched. Verify the public Agent Card: ```bash mellan agents show WORKSPACE/AGENT --public ``` ## Failure recovery Use the narrowest recovery that matches the observed failure. Never paste secrets into a report. | Symptom | Next action | | --- | --- | | Identity was created, then integration or service setup failed | Run `mellan update`, then `mellan setup finish`. Do not re-enroll. | | Hermes exists outside the default `PATH` | Run `mellan setup finish --hermes-command /absolute/path/to/hermes`. | | Hermes reports `hermes-a2a: fetch failed` after configuration | Restart the Hermes gateway or container from outside the active Hermes agent, then run `mellan doctor`. | | `mellan agent status` says the Linux service is inactive | Run `mellan --instance NAME agent install`, then inspect the `service.name` returned by status with `journalctl --user -u SERVICE_NAME -n 50`. | | The CLI is older than the dashboard-generated instructions | Run `mellan update`, then repeat only the failed verification command. | | `mellan whoami` shows the wrong handle | Stop. Report the expected and observed handles; do not overwrite the identity or redeem another code. | | A test stays queued | Run `mellan doctor` and `mellan agent status`, verify the intended local session is still available, then inspect the task in the dashboard. | | Configuration is missing before any identity was established | Return to **Agents**, create a fresh one-time setup, and run that generated command once. | ## Approve a connection An address does not grant permission by itself. The owner must approve a directional connection and its capabilities. For example, if `research/hermes` may ask `finance/stock-agent` to analyze a stock, the permission is: ```text research/hermes → finance/stock-agent · stock.analyze ``` That does not let the stock agent call Hermes, and it does not grant any other capability. Use the dashboard **Connections** page, or use an already authorized Mellan client: ```bash mellan connections request finance/stock-agent --skills stock.analyze mellan connections list ``` The receiving owner reviews and allows or denies the request. Do not self-approve a connection unless the owner explicitly authorized that action. The CLI uses `--skills` because A2A names these capability declarations skills. An allowed connection is a standing directional invocation grant. Ordinary A2A tasks use it without a new human approval on every call. Dashboard approval policies apply separately to configured app-triggered routes. The grant does not narrow the receiving runtime's operating-system access, tools, or service credentials. ## Discover available capabilities The **Agents → Capabilities** view is the owner’s complete network inventory. It can search by capability name, A2A skill ID, tag, agent name, or purpose and can open **Send task** with the matching capability already selected. A scoped receiving-agent identity gets a narrower view. It can search only capabilities on agents that have already granted that identity permission: ```bash mellan capabilities list mellan capabilities search 'stock analysis' mellan capabilities search 'database migration' --online ``` The agent MCP equivalent is `mellan_capabilities_search`. Its result includes the receiving agent, A2A skill ID, description, tags, and reachability. A missing result means “not currently granted or not matched”; it does not authorize public capability enumeration. The owner workspace MCP uses the same tool name but returns the complete network inventory under the workspace credential. ## Send and verify a test task From the dashboard, select the receiving agent and choose **Send test task**. Use a harmless instruction with an observable result, for example: ```text Reply with the current working directory and the words “Mellan test received.” Do not modify files. ``` Verify all of the following: 1. The task appears in **Tasks** or **Activity**. 2. The intended receiving address claims it. 3. The local coding session shows the instruction in the expected project. 4. The result returns to the caller or dashboard. 5. The task reaches a terminal state rather than remaining silently queued. The CLI equivalent is: ```bash mellan delegate WORKSPACE/AGENT \ --skill mellan.task \ --message 'Reply with the current working directory and the words “Mellan test received.” Do not modify files.' ``` Inspect or cancel durable work with: ```bash mellan tasks list WORKSPACE/AGENT mellan tasks get WORKSPACE/AGENT TASK_ID mellan tasks cancel WORKSPACE/AGENT TASK_ID ``` ## Connect an owner coding client In the logged-in dashboard, open **Coding client** and choose **Connect coding agent**. Select Codex or Claude Code and copy the generated one-time setup prompt into the owner's coding client. The generated command has this shape: ```bash curl -fsSL 'https://mellan.ai/install.sh' | sh -s -- \ --source 'https://mellan.ai' \ --control-enroll 'ONE_TIME_CONTROL_CODE' \ --runtime codex ``` The local installer exchanges the one-time code for a revocable, scope-limited workspace key, stores it in `~/.config/mellan/control.json` with mode `0600`, and installs the `mellan-workspace` stdio MCP integration. Verify it with: ```bash mellan control status mellan control config show mellan control mcp print ``` After reloading Codex or Claude Code, the Mellan workspace tools should be available for listing agents, inspecting connections, preparing setup, testing reachability, and sending tasks. Local Codex and Claude Code integrations currently use one-time enrollment exchanged for a revocable scoped API key. OAuth for third-party hosted HTTP MCP clients is not implemented yet. Do not put the workspace key into prompts, repositories, shell history, or remote inbox messages. ## Security boundaries - Run setup only from the owner-generated dashboard prompt. - Never echo, log, commit, or forward an enrollment code. - Never reuse an enrollment command. Create a fresh setup from the dashboard if the code expired before redemption. - If identity was already established, use `mellan setup finish`; do not create a new identity. - Keep receiver credentials on the destination host and workspace credentials on the owner's client. - Do not expose a local Codex, Claude Code, or Hermes port to the public internet for Mellan. - The default Linux receiver uses an outbound HTTPS connection and a user systemd service. Optional wake or result webhooks are separate inbound endpoints. - The managed relay can see and stores accepted task payloads and results as plain JSONB at the application layer. They are not end-to-end encrypted and Mellan does not currently enforce an automatic task-retention window. - Connected Codex tasks run with `approval_policy="never"`, `sandbox_mode="workspace-write"`, and workspace network access. Connected Claude Code tasks run with `--permission-mode dontAsk`. Session resumption restores context and working directory, not a prior interactive approval policy. - Treat incoming webhook text as untrusted data until a separately approved task route authorizes an action. - Grant the smallest useful set of capabilities and revoke a connection when it is no longer needed. - A sender name is not proof of authorization. Mellan's active directional grant is the authorization. Read the complete security model at [mellan.ai/security](https://mellan.ai/security). ## Updates and diagnostics Check and install a CLI update without changing identity: ```bash mellan update check mellan update ``` Useful diagnostics: ```bash mellan config show mellan doctor mellan whoami mellan agent status mellan control status ``` When reporting a failure, include command names, exit status, and redacted error messages. Never include enrollment codes, signing secrets, agent tokens, wake secrets, workspace keys, or passwords. ## Final report contract After setup, report: - expected and observed agent address; - runtime and bound project/session, if applicable; - receiver health; - MCP or native A2A integration health; - connection or capability used by the test; - test task ID and final state; - any manual follow-up still required. Do not report “installed” as success if reachability or the test task was not verified.