Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
RPC Proxy
External-facing user-scoped JSON-RPC proxy for MCP servers and MCP hosts.
Security Model
- Clients authenticate with
external-rest-apifirst. - Clients request RPC access tokens via
external-rest-api(POST /api/v1/rpc/token). control-apiissues/signs the RPC JWTs via internal endpoints.rpc-proxyvalidates issuer, audience, signature, scopes, and expiry.- Access is enforced by:
- user-to-context mapping from
control-api(userId -> contextIds) - allowed MCP servers returned by
control-apifor each user - allowed MCP hosts returned by
control-apifor each user - scope checks (
mcp:servers:list,mcp:server:invoke,host:message:invoke,host:status:read,host:health:read,host:activity:read) - upstream server URLs provided by
control-api
- user-to-context mapping from
Control API Discovery
rpc-proxy resolves access and MCP connectivity through control-api:
- uses JWT
subasuserId - calls
control-apiforcontextIdsand allowed MCP servers (including URLs) - caches user access/server lookups in-memory for a short TTL
- treats
teamIdin the token as informational; authorization is user/context based
Endpoints
GET /healthGET /api/v1/rpc/servers(requiresmcp:servers:list)POST /api/v1/rpc/:serverName(requiresmcp:server:invoke)POST /api/v1/rpc/hosts/:hostRef/messages(requireshost:message:invoke)GET /api/v1/rpc/hosts/:hostRef/activity(requireshost:activity:read)GET /api/v1/rpc/hosts/:hostRef/activity/stream(requireshost:activity:read)GET /api/v1/rpc/hosts/:hostRef/status(requireshost:status:read)GET /api/v1/rpc/hosts/:hostRef/status/stream(requireshost:status:read)GET /api/v1/rpc/hosts/:hostRef/health(requireshost:health:read)
Host Runtime Contract
Host runtime routes in rpc-proxy are REST-oriented and scope-specific. The status stream is a read-only telemetry channel.
| Endpoint | Method | Required Scope | Access Type | Transport |
|---|---|---|---|---|
/api/v1/rpc/hosts/:hostRef/messages |
POST |
host:message:invoke |
Write | REST |
/api/v1/rpc/hosts/:hostRef/activity |
GET |
host:activity:read |
Read | REST |
/api/v1/rpc/hosts/:hostRef/activity/stream |
GET |
host:activity:read |
Read-only | SSE |
/api/v1/rpc/hosts/:hostRef/status |
GET |
host:status:read |
Read | REST |
/api/v1/rpc/hosts/:hostRef/health |
GET |
host:health:read |
Read | REST |
/api/v1/rpc/hosts/:hostRef/status/stream |
GET |
host:status:read |
Read-only | SSE |
Notes:
status/streamdoes not accept request bodies and must not be used for message submission.activity/streamis read-only telemetry and never accepts message submission payloads.activityandactivity/streamnever include chain-of-thought/internal reasoning text.- Message submission is only via
POST /api/v1/rpc/hosts/:hostRef/messages.
POST /api/v1/rpc/:serverName expects a JSON-RPC 2.0 request body:
{
"jsonrpc": "2.0",
"id": "1",
"method": "tools/list",
"params": {}
}
POST /api/v1/rpc/hosts/:hostRef/messages expects a REST request body:
{
"content": "hello from desktop",
"channelType": "rpc",
"sender": "desktop-app"
}
Host Message Authorization Flow
sequenceDiagram
participant Desktop as desktop-app
participant Proxy as rpc-proxy
participant Gateway as control-api-rpc-gateway
participant Control as control-api
participant Host as mcp-host/<hostRef>
Desktop->>Proxy: POST /api/v1/rpc/hosts/:hostRef/messages (Bearer RPC JWT)
Proxy->>Proxy: Verify RS256 JWT + iss/aud + typ=user + exp + scope + hostRefs
Proxy->>Gateway: GET /api/v1/rpc/access/users/:userId/mcp-hosts/:hostRef
Gateway->>Control: Forward allowlisted path
Control->>Control: Validate internal caller + x-rpc-access-token + claim binding
Control-->>Proxy: { userId, hostRef, url } or 403
Proxy->>Host: POST /v1/runtime/messages
Host-->>Proxy: runtime response
Proxy-->>Desktop: REST response body
Required JWT claims for host message path:
typ=usersub=<userId>teamId=<teamId>scopesincludeshost:message:invokehostRefsincludes target:hostRef(wildcard*is rejected)iss,aud,iat,exp,jtivalid
Troubleshooting
401 Unauthorized: token malformed/expired/wrong issuer-audience/signature.403 Forbidden: missing scope: token does not include the required route scope.403 Forbidden: user cannot access this host: host not in tokenhostRefsand/or denied bycontrol-apiRPC-access policy.504 Gateway Timeout: upstream MCP target unreachable (check network policy and service reachability).
Environment
See .env.example.
Critical variables:
RPC_PROXY_JWT_PUBLIC_KEYRPC_PROXY_JWT_ISSUERRPC_PROXY_JWT_AUDIENCERPC_PROXY_CONTROL_API_BASE_URLRPC_PROXY_CONTROL_API_CACHE_TTL_MS
Required in production:
RPC_PROXY_CONTROL_API_SERVICE_TOKEN
RPC_PROXY_JWT_PUBLIC_KEY must match the public key for CONTROL_API_RPC_JWT_PRIVATE_KEY.
Local Run
Use Node 24 or newer. Start control-api first with CLERUM_DEV_MODE=true
so it creates the shared development signing keys, then start this service in
a separate terminal:
cd rpc-proxy
npm install
CLERUM_DEV_MODE=true npm run dev
make dev also opts into this local mode. It is rejected with
NODE_ENV=production. Without this opt-in, set RPC_PROXY_JWT_PUBLIC_KEY
explicitly.
The shared store defaults to control-api/.dev-keys in the same checkout.
Leave EVENFIRE_DEV_KEY_STORE unset or blank to use that default; a nonblank
override must be an absolute path set consistently in all three services.
control-api persists generated keys across restarts, and this service reads
rpc.public.pem at startup.
If CONTROL_API_RPC_JWT_PRIVATE_KEY is supplied through the environment, set
RPC_PROXY_JWT_PUBLIC_KEY to its matching public key explicitly. The signer
does not update the store for an environment-supplied key, so an older store
may contain a different identity. After deleting or rotating stored keys, or
switching to an environment-supplied key, reconfigure the verifier as needed
and restart it. Running verifiers do not silently refresh their key identity.
JWT material is checked by the shared @clerum/jwt-key-policy. Configure an
RSA public key as SPKI or PKCS#1 PEM. An X509 certificate may carry the public
identity, without CA, hostname or expiry validation. Private PEM environment
values remain accepted for legacy compatibility and are converted to public
SPKI; prefer supplying only the public half. Store public files reject private
material. Exactly one complete PEM object is required; bundles, encrypted
private material, non-RSA keys and historical committed identities fail.
Every RS256 key must be RSA-2048 or stronger, including verifiers. This deliberately rejects previously accepted weak verifier keys under RFC 7518 section 3.3. The material/read limit is 64 KiB. Invalid explicit input never selects a different source or regenerates an identity.
The dev store requires POSIX no-follow/nonblocking/exclusive-file guarantees, trusted ancestor directories and cooperating services with the same effective UID. It does not defend against hostile ancestors or same-UID processes. Use explicit signing/verifying environment keys for different users or unsupported platforms; this verifier then performs no store access. Corrupt or rejected keys require operator repair; they are not rotated automatically.
make docker-build uses the repository root context. The equivalent command
from that root is docker build -f rpc-proxy/Dockerfile .. The image preserves
the service/package layout and excludes package tests and local key data.
Kubernetes Deploy (Hardened Defaults)
The deploy/ manifests include:
- non-root container +
RuntimeDefaultseccomp - dropped Linux capabilities
- read-only root filesystem with writable
/tmp - resource requests/limits and health probes
- ingress TLS and basic rate limiting annotations
- restrictive
NetworkPolicyandPodDisruptionBudget
Before deploying, create a real secret from deploy/example.secret.yaml values:
kubectl create secret generic rpc-proxy-secrets -n rpc-proxy \
--from-literal=RPC_PROXY_JWT_PUBLIC_KEY='-----BEGIN PUBLIC KEY-----\nreplace-with-rs256-public-key\n-----END PUBLIC KEY-----' \
--from-literal=RPC_PROXY_CONTROL_API_SERVICE_TOKEN='replace-with-rpc-proxy-token'
Then deploy:
cd rpc-proxy
make deploy
Update deploy/ingress.yaml host/TLS secret and deploy/networkpolicy.yaml selectors/ports for your cluster.