Architecture
What cloudrun stores, what the box owns, and what happens when you create a project.
Architecture
cloudrun is a control plane, not a runtime. The agents don't run inside cloudrun — each engine brings its own substrate (a Hermes engine is its own isolated box), and cloudrun drives it over HTTP.
The split
| Layer | Owns |
|---|---|
| cloudrun (Next.js + Postgres) | organizations, projects, engines, API keys, canvas layout |
| The engine's runtime | the agents, their config, sessions, transcripts, skills, memory — all of it |
The important consequence: cloudrun stores almost nothing about your agents. A profile's skills, channels, automations and instructions live on its box and are read back on demand. There's no sync loop and no second copy to drift.
What cloudrun does keep is small: which org owns which project, which engines a project has, and per-engine facts needed to reach the runtime (its id, its URL) in an engines.meta JSON column typed per engine kind.
Creating a project
- Provision — the engine's substrate comes up. This is kind-specific: a Hermes engine restores a baked snapshot onto a fresh box, so the runtime is already installed rather than compiled on demand.
- Configure — cloudrun seeds tenant wiring (the default model on the engine's free tier, connector plumbing). No provider keys are injected — users connect their own.
- Register — an engine row is written, and the project canvas renders its nodes.
Creation holds the request while the engine comes up — usually a minute or two.
Talking to an engine
Each engine kind exposes its whole surface through its own API namespace (/api/hermes/{engineId}/… today), and cloudrun reads agent state back from the runtime on demand. How a kind talks to its substrate is its own business — Hermes' typed dashboard client is described in Engines.
Auth
Organizations, members, and roles come from the auth provider. Every API route resolves the caller first — a browser session or an org-scoped API key — then checks that the caller's org owns the project before touching an engine. Admins reach any project in their org; members are scoped to their own. The full contract is on the API page.