mellan
Create network

Architecture

Mellan is a managed identity, authorization, and durable-delivery layer for agents that live in different environments. It lets a caller ask a receiving agent for a declared capability without making the receiving agent a publicly reachable server or copying its destination service credentials to the caller.

Components

  • Managed control plane: workspace membership, agent inventory, directional grants, audit history, enrollment, and the dashboard.
  • Managed relay: A2A entry point and durable task state. It authenticates callers, checks grants, stores work, coordinates leases, and returns results.
  • Outbound receiver: a service beside the destination agent. It polls or streams for authorized work, runs the configured adapter, and reports state and results.
  • Runtime adapters: integrations for connected Codex, Claude Code, and Hermes sessions plus configured fresh provider runs.
  • Calling clients: another A2A agent, the Mellan CLI, an owner coding-client integration, or an approved app-triggered route.

The agent-side connector and protocol code are intended to be source-auditable. The managed dashboard, database, and relay service remain the hosted control plane.

Identity and discovery

Each agent has a stable workspace-scoped identity. A public Agent Card reveals only the connection capability. An authenticated caller receives an extended view filtered to capabilities it has an active grant to invoke. Workspace-owner clients can inspect the whole private inventory.

Discovery is therefore not a public registry. The caller sees only the part of the network that its credential and grants allow.

Directional capability grants

A grant is a tuple of calling agent, receiving agent, and one or more exact capability identifiers. Direction matters: permission for local/codex to invoke incident.inspect on private/ops does not authorize the reverse route or another capability.

The grant authorizes invocation. It does not modify the tools, sandbox, service account, or operating-system permissions of the receiving runtime. Those remain destination responsibilities.

Task flow

  1. The caller discovers a granted capability and sends an A2A task.
  2. The relay authenticates both identities and checks the active directional grant.
  3. The relay persists the task and exposes current task state to the caller.
  4. The destination receiver claims the task with a renewable lease.
  5. The selected adapter resumes a bound session or starts the configured fresh run.
  6. The receiver records progress, result, and artifacts, or reports cancellation/failure.
  7. The caller polls, waits, or reconnects to observe the terminal state.

If the destination is offline, accepted work remains queued. Cross-replica notifications reduce latency, but Postgres and periodic reads are the durable source of truth.

Leases, retries, and cancellation

Claims are atomic and time-bound. A receiver renews its lease while work is active. Expired work can be reclaimed according to the bounded retry policy, while tasks sharing a bound session are serialized.

Execution and completion delivery have separate boundaries. Once a successful execution is recorded, Mellan retries reporting that completion rather than running the successful work again. Cancellation revokes an active lease; the receiver detects the loss and terminates supported coding-agent subprocesses.

Session resumption

For connected Codex or Claude Code, Mellan binds an approved task route to an existing session identifier and working directory. That preserves conversation context, but queued execution uses Mellan's configured unattended profile rather than the session's former interactive approval mode. The exact defaults are documented in Security.

Hermes uses its native loopback A2A integration. Fresh-run adapters create new provider work for each authorized task instead of binding a local conversation.

Connectivity

The default receiver initiates outbound HTTPS and requires no inbound listener. Linux automatic installation uses a user systemd service. Operators may separately configure signed wake or result webhooks, and deployments may use mTLS for supported receiver paths.

Mellan can run over a VPN or private underlay, but it does not replace one. It adds agent identity, capability grants, task durability, session routing, and returned-result semantics.

Data visibility

The relay is in the task data path. It sees and stores accepted task payloads, metadata, results, and artifacts. These fields are ordinary JSONB at the application layer and are not end-to-end encrypted. See Security before routing sensitive work.

Protocol surface

Mellan exposes A2A 1.0 Agent Card, task submission, task lookup, cancellation, and streaming behavior. Streaming is reconnectable state observation, not a promise to replay every historical SSE event. Optional push-notification configuration is not currently implemented.

What Mellan is not

  • It is not an execution sandbox around the destination agent.
  • It is not a workflow engine deciding which steps run next.
  • It is not a VPN providing machine-level network reachability.
  • It is not a public or universal agent registry.

Those boundaries are deliberate: Mellan coordinates authorized delegation while execution remains in the environment chosen by the operator.