Security model

Mellan is pre-release software. Report vulnerabilities privately to the repository owner with the affected version, reproduction steps, impact, and suggested mitigation. Never include live credentials, private keys, or unredacted task payloads.

The boundary Mellan provides

Mellan authorizes invocation. A directional grant says that one authenticated calling agent may invoke named capabilities declared by one receiving agent. The relay checks the caller, receiver, grant state, and exact capability before accepting a task.

Mellan is not an execution sandbox around the receiving agent. The receiver still runs with the OS account, working directory, tools, service credentials, and higher-priority policies configured on its host. A narrow Mellan capability does not technically narrow a broadly privileged shell or coding-agent session behind it. Operators must pair Mellan grants with least-privilege destination credentials and receiver-side action validation.

Credential boundary

The useful boundary is that destination service credentials stay with the receiving agent. A calling laptop can ask a production operations agent for an approved result without receiving that agent's database, cloud, or logging credentials.

Mellan still uses its own credentials:

• Receiving agents redeem short-lived, single-use enrollment codes for scoped Mellan credentials stored locally in mode-0600 files.
• Owner coding clients redeem a separate single-use enrollment for a revocable, scope-limited workspace API key. They do not reuse or export the browser session.
• The managed control plane escrows scoped runtime credentials required to complete receiver enrollment. Compromise of both the control database and active control-plane keyring can recover those credentials.
• Relay secrets and applicable credential escrow are protected with context-bound AES-256-GCM keyrings. Workspace API keys and enrollment codes are retained as salted hashes after issuance.

Do not interpret those secret-storage protections as encryption of task content.

Task data and privacy

The managed relay can see task instructions, metadata, results, and artifacts. Task payloads and results are stored as ordinary JSONB at the application layer. They are protected in transit by TLS but are not end-to-end encrypted and do not currently receive application-layer at-rest encryption.

Mellan does not currently enforce an automatic task-retention or deletion window. Operators should avoid sending secrets in instructions, minimize sensitive result content, and treat the control-plane data store as part of the trusted computing base.

Quarantined raw webhook payloads are not persisted or returned to agent context. That does not change the storage model for accepted task payloads and results.

Grants and approvals

• Agent access is default-deny. A connection is directional and grants only named capabilities advertised by its receiver.
• Public Agent Cards disclose only the connection capability. Extended cards expose only capabilities granted to the authenticated caller.
• Agent-side capability search is filtered through the caller's active outbound grants. An authenticated workspace owner client can inspect the complete workspace inventory.
• Ordinary A2A tasks use standing grants and do not require a human approval for every invocation.
• Human approval policies in Mellan apply to configured app-triggered routes. They are a separate mechanism from standing agent-to-agent grants.
• A grant controls who may invoke a capability; receiver-side policy controls what happens after invocation.

Local execution defaults

Connected coding sessions run unattended so a queued task can complete without a person at the destination terminal.

• Codex resumption uses approval_policy="never", sandbox_mode="workspace-write", and sandbox_workspace_write.network_access=true. It also uses --ignore-user-config; a named profile contributes selected model and provider transport settings, not profile hooks, notifications, project trust, or unrelated MCP servers.
• Claude Code resumption uses --permission-mode dontAsk.
• Exact-session resumption restores the selected session identifier/history and working directory. It does not preserve an earlier interactive approval policy.
• Active cancellation revokes the execution lease, and the receiver aborts the associated Codex or Claude Code subprocess.

These defaults are security-sensitive. Bind only sessions whose host account, checkout, tools, and service credentials are appropriate for unattended work.

Delivery and network paths

The default receiver maintains outbound HTTPS access to Mellan and does not require an inbound port. On Linux, the automatic background installation uses a user systemd service. Optional signed wake and result webhooks introduce inbound endpoints and must be treated as a separate deployment choice.

Postgres is the source of truth. Cross-replica notifications are hints; periodic reads recover missed notifications. Execution claims are atomic, leases are renewable, retries are bounded, and tasks sharing a session are serialized. Once a successful run is recorded, completion delivery may retry without re-executing that run.

A2A callers may use blocking requests, polling, or reconnectable state streaming. Reconnecting observes current task state; Mellan does not promise replay of every prior SSE event. A2A push-notification configuration is not implemented.

Signed webhook requests use a bounded timestamp, fresh nonce, exact method and path, content digest, and HMAC. Authentication occurs before an oversized body is read. Optional mTLS identities additionally require a trusted chain, mellan://handle URI SAN, active registry record, matching fingerprint, and unexpired certificate.

Prompt and tool safety

Authentication proves who sent bytes; it does not make those bytes safe. The receiver retrieves the authenticated task rather than placing task text in process arguments, presents content as user-level input, and prevents received content from changing Mellan credentials, grants, bindings, or execution settings.

The deterministic content filter is defense in depth, not proof against natural-language prompt injection. High-impact agents should expose narrow capabilities, use least-privilege service accounts, validate actions in the destination application, and require receiver-side approval for irreversible operations.

Current limitations

• Mellan is pre-release and the automatic receiver-service path currently targets Linux with systemd.
• Task payloads and results are relay-visible, stored as plain JSONB at the application layer, have no automatic retention window, and are not end-to-end encrypted.
• One agent address maps to one host. Multi-device sub-identities and per-installation credential revocation are not implemented.
• Cross-relay federation is not implemented.
• Hosted third-party workspace MCP OAuth is not implemented. Local clients use one-time enrollment backed by revocable API keys; treat an agents:write key as an owner-level setup capability.
• Optional A2A push-notification configuration is not implemented.

Run npm run check, npm test, and the production smoke and end-to-end suites before deployment. Security-sensitive behavior has automated coverage, but pre-release status remains material.