pronounced "eh‑feer"
Ephyr
Cryptographically bounded agent authority
with centralized audit.
The first open-source implementation of the Delegation Capability Token architecture from Google DeepMind's "Intelligent AI Delegation" framework.
Ephyr Architecture Whitepaper
Dual-process design, MCP server implementation, HTTP proxy engine, federation, policy engine, task identity, dashboard, metrics, and deployment topology.
Read →Security Whitepaper
Trust model, authentication layers, cryptographic choices, network isolation, hardening guide. 14 enumerated threats with mitigations.
Read →Task-Scoped Portable Identity
Why task runs—not service accounts—should be the unit of agent identity. CTT-E tokens, capability envelopes, epoch watermarks.
Read →The Problem
MCP gives agents tools. It doesn't govern what happens when agents delegate to sub-agents, when permissions need to attenuate, or when actions need to trace back to the task that initiated them.
Static credentials are a liability
SSH keys don't expire. API tokens can't be scoped per-task. When an agent session ends, the access remains. Rotation is manual and error-prone.
No delegation model
When agent A delegates to B, and B delegates to C—who authorized C to do what? MCP has no policy layer for permission propagation across delegation chains.
Authority can't be proven
Can you prove the authority only narrowed? Without cryptographic caveat accumulation and deterministic reduction, the answer is no.
What Ephyr Does
An access broker between AI agents and infrastructure. One MCP endpoint replaces scattered credentials with policy-governed, ephemeral, SIEM-ready access.
Agent (MCP client)
│
│ Bearer: mac_<base64url macaroon>
│
▼
┌──────────────────┐ ┌──────────────────┐
│ ephyr-broker │ IPC │ ephyr-signer │
│ ├──────────▶│ │
│ Policy engine │ │ CA key custody │
│ Macaroon verify │ │ SSH cert signing│
│ HMAC reducer │ │ Never on network│
│ Audit logger │ └──────────────────┘
│ HTTP proxy │
│ MCP federation │
│ Task identity │
└────┬───────┬─────┘
│ │
SSH certs HTTP proxy MCP federation
│ │ │
▼ ▼ ▼
Targets Services Remote MCP serversephyr-signer
Holds the Ed25519 CA private key in a systemd sandbox. ProtectSystem=strict, MemoryDenyWriteExecute, zero capabilities. Unix socket IPC only. The CA key never leaves this process, never touches the network.
ephyr-broker
HMAC chain verification, caveat reduction, policy evaluation, SSH certificate requests, HTTP proxy with credential injection, MCP federation, task tree management, structured audit, admin dashboard.
How It Works
HMAC-Chained Macaroons
Task tokens use HMAC-SHA256 caveat chains. Restriction removal is cryptographically impossible. The effective envelope reducer derives the most-restrictive authority using set intersection, minimums, and boolean AND.
Ephemeral SSH Certificates
Ed25519 certificates with 5-minute default TTL. Per-request issuance by the isolated signer. Persistent sessions reduce latency from ~850ms to ~14ms—60x faster for sequential commands.
Task-Scoped Identity
Every action correlates to a task run with a ULID. Capability envelopes bound what a token can do. Epoch watermark revocation invalidates entire task trees instantly—O(depth), no blocklists.
Broker-Mediated Delegation
Parent tasks delegate to children with attenuated scope. Cross-agent delegation supported. The child gets the intersection of parent ceiling and child policy. Max depth 5. No offline delegation.
Policy & RBAC
Declarative YAML, hot-reload via SIGHUP. Eight-step evaluation pipeline. Per-agent RBAC across SSH, HTTP, and MCP federation with template inheritance and wildcard support. Every denial includes a reason.
Three Proxy Paths
SSH certificates, HTTP APIs with credential injection (bearer, basic, header, query param), and federated MCP servers with automatic discovery. Agents connect once; the broker handles everything.
15 MCP Tools · 7 Resource URIs
JSON-RPC 2.0 over Streamable HTTP, implementing MCP 2025-03-26. Works with Claude Code, Claude Desktop, Cursor, Cline, and any MCP client.
Infrastructure
exec— Run commands via ephemeral SSH certsession_create/session_close— Persistent sessionslist_targets/list_sessions/list_certs
HTTP Proxy
http_request— Authenticated proxy (credentials auto-injected)list_services
Task Identity & Delegation
task_create/task_delegate— Scoped tasks with attenuationtask_info/task_list/task_revoke
Resources (Self-Discovery)
ephyr://overview— System summary + permissionsephyr://targets/ephyr://services/ephyr://rolesephyr://status/ephyr://tools/ephyr://remotes
Capability Tiers
Each tier is a strict superset of the previous.
Ephyr Core
v0.1 – v0.2a
Brokered access, ephemeral credentials, task-scoped identity with ULID correlation, declarative policy with hot-reload, RBAC, epoch watermark revocation, structured audit trail.
Does not enforce command-level filtering (delegated to host shell + sudoers) or push certificate revocation to hosts.
Ephyr Delegation
v0.2b
Pure-stdlib macaroon engine (HMAC-SHA256). Fuzz-tested reducer (220k executions). Broker-mediated delegation with cryptographic caveat accumulation. Cross-agent delegation. ephyr inspect CLI.
Bearer tokens. A leaked macaroon can be used until TTL/watermark. Holder binding is Ephyr Bind.
Ephyr Bind
v0.3
DPoP-style proof-of-possession. Ephemeral Ed25519 keypair per task. Leaked macaroons are useless without the corresponding private key. No mTLS infrastructure required.
By the Numbers
Benchmarked on Debian 12 LXC, 1 vCPU, 512MB RAM. Macaroon implementation is pure stdlib (HMAC-SHA256 from crypto/hmac).
Security Model
Defense in Depth
Five authentication layers: SO_PEERCRED (kernel-verified UID), 256-bit session tokens, constant-time dashboard auth, bcrypt API keys, and Ed25519 SSH certificates.
CA Key Isolation
The CA private key exists only in the signer process. Systemd sandbox with ProtectSystem=strict, MemoryDenyWriteExecute, and zero capabilities. Never on the network.
Network Isolation
nftables UID-based rules block direct agent-to-backend traffic. All access routes through the broker. CIDR allow/deny policy for HTTP proxy destinations.
14 Enumerated Threats
Documented threat model covering broker compromise, agent takeover, token leakage, network attacks, and more. Each threat has explicit mitigations and residual risk assessment.
Built for homelabs and internal engineering teams.
Designed for environments where you trust the operator but need to control what agents can do. Not multi-tenant. Not a managed service. Your infrastructure, your policy, your audit trail.
Apache 2.0 · Go 1.24+ · Linux · 3 dependencies · Zero external databases