Skip to content

Architecture v0.1.0 — local core (2026-09-27)

First release: the three runtime components, the local compose stack, and a conformance harness.

  • runtime-py ramen_runtime: modules proto, loader, secrets, prompts, executor, deps, rpc, log. Loads mcp/{tools,resources,prompts}/<name>/ packages, validates each <name>.json against a JSON Schema (folder == name == file stem, type matches folder), adds utils/ to sys.path, pip-installs mcp/requirements.txt when its hash changes, substitutes {{$group.VAR}} from RAMEN_SECRET_<GROUP>__<VAR>. Newline-delimited JSON-RPC 2.0 on stdin/stdout. 43 tests, 98 % coverage.
  • node-rs ramen-node (axum/tokio): POST /mcp (initialize, ping, tools/list|call, resources/list|read, prompts/list|get; protocol 2025-06-18, JSON responses only), GET /healthz, /readyz, /metrics, POST /admin/reload gated by X-Ramen-Admin-Key. Bearer keys from RAMEN_MCP_KEYS ∪ config file ∪ deploy file; CIDR allow-list; RAMEN_MAX_INFLIGHT bound; sidecar killed after RAMEN_SIDECAR_IDLE_SECS. One image (node-rs/Dockerfile, python:3.14-slim, ~250 MB) holds both node and runtime. 94 % line coverage.
  • console: FastAPI + Jinja2 + HTMX. Storage adapters memory | firestore | dynamodb behind Store.get/put/delete/list/transaction; sensitive fields Fernet-encrypted. Cloud adapter local (filesystem bucket, deploy = write <bucket>/.ramen/env-<zone> + POST /admin/reload). Roles super_admin / group_admin / viewer, signed-cookie sessions, argon2 passwords, rmn_ API keys, rmk_ MCP keys, audit middleware, deploy jobs as background tasks, backups as JSON. 63 tests, 98 %.
  • deploy/local: compose (Firestore emulator :8081, console :8443 self-signed, worker :8080), make demo (zone → group → env → key → deploy → tools/call → 5), make demo-worker (node + runtime without Docker).
  • tests/: conformance suites for §1–§4 that run against URLs and skip without env; e2e demo flow; CI with version check, coverage artifacts, compose e2e; release workflow on v* tags.

Known gaps at 0.1.0: no CSRF token, in-memory job table, lock-based Store.transaction, gcp/aws adapters stubs, no tool blocking, no SMTP.