Loopy — Deployment Architecture

The concrete pieces of a running Loopy, how they wire together, and what changes from laptop to production.

1. The two lifecycles

A Loopy deployment has a build-time path and a run-time path, joined by one artifact: the manifest.

• loopy compile parses the project, resolves the DAG, statically checks every {{ event.* }} / {{ step.* }} reference, and emits manifest.json (plus generates loopy.events for sensor authors). It executes nothing and has no runtime dependency — it belongs in CI. A green compile is the deploy gate.
• loopy run manifest.json is the server. It loads the manifest, stands up the sensor webhooks, and runs workflows as events arrive. It never reads .md — the manifest is the complete IR, which is what makes "edit a workflow, recompile, redeploy" safe.

The deploy unit is therefore manifest.json + the project root — the root is still needed at run time for two things only: the sensor module source and the sandbox env_files.

2. Anatomy of a successful deployment

The Loopy server in the middle, the outside world it integrates with on the edges. The agent never calls the model from the Runtime process — the AgentHarness shells out to claude inside the Sandbox, so model calls and tool side effects originate from the Sandbox and are governed by its network: allowlist.

egress from the sandbox is gated by the network: allowlist

The pieces, and what ships today

3. Compute topology: the physical boundaries

Section 2 is the logical pipeline — the order data flows through. This is the physical one: which OS process and trust domain each piece runs in. Architecturally there are five tiers, and the EventBus is the seam — everything above it is ingress, everything below it is execution, and the two halves talk only through it.

Five facts this makes explicit — and that the logical pipeline leaves ambiguous:

• The SensorRunner is its own domain, and it's untrusted. It runs developer code, possibly in another language (TypeScript via the SDK) in an app you already operate. It produces a candidate event and hands it off — it never touches the EventBus or the Runtime directly.
• The EventReceiver is the trusted front door — on the producer side of the EventBus, not in the Runtime. Its only job is producer-facing: authenticate the sender and re-validate the event against the registry contract (never trust the producer), then publish. It runs no workflows. (Where it physically runs is the next callout.)
• The EventBus is the one modular seam between ingress and execution. Swap the in-process implementation for a broker (Redis/NATS/Kafka) without touching a tier above or below — that is the entire point of the EventBus Protocol. It also buffers: the EventReceiver keeps accepting and enqueuing while the Runtime is busy or restarting.
• The Sandbox is the one hard process boundary that always exists — even on a laptop. The agent never runs in the Runtime process; Sandbox.exec puts it in a child subprocess (local) or a remote container (daytona). That boundary is the trust/egress boundary: secrets are injected into it, and its network: allowlist governs what the agent can reach.
• The AgentHarness straddles the Runtime ↔ Sandbox boundary. Its orchestration (render the prompt, build the argv, parse/validate the JSON envelope, enforce the budget) runs in the Runtime process; the agent it launches runs in the Sandbox. It's the one component that reaches across.

What crosses each boundary

3.1  Physical topology — today, and where we're going

The tiers are logical; how many processes they occupy is a deploy choice. The direction is a service-oriented architecture: the EventReceiver and the Runtime become separate services that talk through a broker. For now we run them as one node — the simple starting point — and evolve outward. Switching modes changes only which EventBus you wire in; no .md changes, no recompile.

Two things hold in both modes:

• The Sandbox is always separate. Even single-node runs the agent in its own sandbox (a local subprocess or a daytona container) — it is never part of the receiver/engine node.
• Everything on the bus is already valid, so sensors never write to the EventBus directly. The SensorRunner is untrusted (developer code, maybe another language, maybe in your own app); the EventReceiver is the gate that authenticates it and re-validates the event against the registry contract before publishing. A sensor writing to the bus directly would skip that check (and a remote one can't reach an in-process bus anyway, and shouldn't get direct broker write access). That gate is the receiver's entire reason to exist. (See the sensor-surface note for the SDK model that puts the SensorRunner in your own app.)

3.2  Staying out of the corner

Today sensors are loopy-hosted in Python (the simple start). The plan is to expand to developer-hosted sensors later — the dev's own app/language posting events to a loopy-owned endpoint — which is what unlocks polyglot. Getting there cleanly depends on two behaviors, not on extra machinery. The structure is already right (receive() takes a serializable Event, the @sensor fn is a standalone payload → Event callable, the contract is generated as static files), so the only corner risk is shipping the in-process version with the wrong behaviors and calling the interface "ready to split." Two things land now:

1. The EventReceiver re-validates every event against the manifest registry — even though in-process the sensor "should" be correct. Skipping it bakes in sensor-trust; un-trusting it later means adding the gate and auditing everything downstream.
2. receive() publishes and acknowledges — it does not run the workflow synchronously. A remote receiver can't hold a connection open for a minutes-to-days run, so synchronous-run-from-receive must never be depended on. The Runtime consumes off the bus instead.

Deliberately deferred to the developer-hosted milestone (additive, easy to get wrong if built speculatively): the HTTP POST /events endpoint, producer authentication, an external broker, and contract versioning/distribution to remote sensors. The one rule while they're deferred — keep Event serializable and never assume the sensor and receiver share an in-memory registry. (Tracked in plans/future/sensor-ingress/.)

4. The request path of one incident

The README's incidents example, traced through a live deployment:

1. Sentry fires a webhook            ── POST /hooks/sentry ──▶  SensorRunner
2. the @sensor fn maps the payload   ── returns Incident(source=sentry, …) ──▶  EventReceiver
3. EventReceiver injects it          ── Runtime.trigger(Incident) ──▶  EventBus.publish
4. EventBus routes Incident          ── matches triage/investigate `on: Incident` ──▶  a run starts
5. investigate runs                  ── ClaudeCodeHarness runs `claude` in a sandbox ──▶  emits WorkItem
6. WorkItem re-enters the bus        ── matches resolve/arbitrate `on: WorkItem` ──▶  a new run starts
7. arbitrate ▶ fix ▶ review ▶ ship   ── one workflow, `after:` chain, outputs passed by reference
8. ship emits GoalShipped            ── terminal announcement on the bus

Steps 4 and 6 are cross-workflow event seams — they go through the bus. The arbitrate → fix → review → ship chain in step 7 is within-workflow: those handoffs are outputs passed by reference ({{ fix.diff }}) and never touch the bus. Events cross workflow boundaries; outputs stay inside one.

5. Deployment topologies

The same five-axis composition (Runtime · StateStore · EventBus · Harness · SandboxProvider) is wired differently per environment. Only the wiring changes — no .md and no compile step is touched.

loopy.yaml — deployment defaults for loopy run

The run-time wiring choices map to an optional config file so they need not be retyped as flags. Absent the file, defaults apply unchanged.

sensor_server:        # the host:port that binds the sensor-webhook listener
  host: 0.0.0.0
  port: 8000
bus: redis            # inproc (single-process) | redis (networked broker)

Precedence is explicit flag > loopy.yaml > built-in default, so --bus inproc still wins over a file that says redis. Connection strings stay in the environment, never the file: bus: redis reads its URL from the REDIS_URL env var (or the --redis-url flag), defaulting to redis://localhost:6379. sandbox is not a config key and not a launch flag — each sandbox's provider: is declared in registry.yml, and the runtime routes each step to the backend its sandbox names. state: (durable StateStore) and limits: (spend caps) are reserved for B10/B-cost and not yet read.

loopy.env — the secret companion to loopy.yaml

Because connection strings and provider keys can't live in the YAML, a local-dev convenience file supplies them: loopy run reads loopy.env at the project root and merges it into the process env with non-override (a value already set in the real/platform environment always wins), before resolving redis_url and before any Daytona client is created. Infra creds only — REDIS_URL, DAYTONA_API_KEY/DAYTONA_API_URL — gitignored; agent secrets stay in sandbox env_files and sensor secrets in sensors/.env. In production you typically skip the file and inject these from the platform's secret store, which the non-override semantics respect.

# loopy.env (project root; gitignored; local-dev convenience)
REDIS_URL=redis://localhost:6379
DAYTONA_API_KEY=dt-...
DAYTONA_API_URL=https://...

6. The deployment checklist

What you need in place for a successful run, in order:

• A green compile. loopy compile . (writes manifest.json; use --check to validate without writing) exits 0 — every on:/emits: names a registered event, every {{ }} ref resolves, the DAG is acyclic, every sensor declares a registered emits. Run it in CI.
• The manifest, shipped. manifest.json is the deploy artifact; carry the project root alongside it (for sensor source + env_files).
• Agent secrets, as sandbox env_files. Each sandbox's env_file must exist under the project root and hold the keys the harness needs — at minimum the model API key (ANTHROPIC_API_KEY for claude-code). The runtime refuses to start a step whose sandbox can't supply the harness's required keys, and refuses paths that escape the root.
• Sensor secrets, as sensors/.env. Credentials an in-process @sensor needs (a poll API key, a webhook-signing secret) go in a single runner-wide sensors/.env under the project root; loopy run merges them into the process env (non-override) so sensors read them via os.environ. Optional and gitignored. Keep infra creds (DAYTONA_API_KEY, REDIS_URL) out of it — those are the server's own env.
• Control-plane / infra creds. The creds the engine itself needs go in its process env: DAYTONA_API_KEY / DAYTONA_API_URL (for the daytona provider, loopy's default sandbox — the SDK ships in the core deps), and REDIS_URL / --redis-url (for --bus redis). In production these come from the platform; for local dev drop them in loopy.env at the project root (the secret companion to loopy.yaml, merged with non-override). Infra creds only — agent secrets stay in sandbox env_files, sensor secrets in sensors/.env. For the local provider: nothing — but agents run as host subprocesses, so it's dev-only.
• Egress allowlist. Each sandbox's network: list is the egress contract — it must include every host an agent reaches (e.g. github.com for opening a PR), and the model API endpoint must be reachable from inside the sandbox.
• Sensor sources pointed at the server. Each source's webhook must POST to the matching @sensor(webhook="/hooks/…") path. loopy run prints the hosted paths on startup — verify the count and paths match.

7. One-glance summary

The EventBus is the seam: ingress (SensorRunner → trusted EventReceiver) on one side, execution (Runtime → AgentHarness) on the other, talking only through it. The Sandbox is the other hard boundary — where trust and egress are enforced. The manifest is the contract between author and Runtime; the Sandbox is the contract between agent and the outside world.