Runtime

The runtime is the part of Physics that actually executes an operation. When you POST to an operation URL, this is what receives it, validates it, decides where the work happens, runs it, and records the result. One uniform path covers every element in the platform. This page is the reference entry to that path; the concept that teaches the execution model end-to-end is runs.

One executor, many substrates

Every operation enters through the same door:

POST /api/{circle}/{slug}/ops/{operation}

The executor validates the request body against the operation’s declared input schema, recognizes the element’s category from generated metadata, and dispatches — without ever branching on the specific element type. That element-agnostic dispatch is the spine of the runtime: the behaviour of each element type lives in chemistry YAML and flows through generated code, so one handler runs a Python action, a SQL query, an LLM call, and a circle creation alike.

What differs between them is the substrate the executor routes to — the run is a uniform envelope around very different machinery:

• Code actions (python, javascript, go-fn, …) run in a sandboxed Firecracker microVM with zero internet egress. → Pillar: Isolation
• Intelligence operations (a lab/brain call) go through the in-process LLM gateway, which fronts multiple model providers behind one interface.
• Data queries (sql, vector, and the data category) execute against Postgres inside the circle’s own circle_{uuid} schema — never another circle’s.
• IO operations reach the outside world through each element’s own vetted client.

Same envelope, different physics underneath. The dispatch layer routes; the substrates are the compute, storage, and network forces it dispatches to.

What a run records

Every operation becomes a run — the durable record you reason about afterward: its validated inputs, its status, its output or a structured error, its logs, and the AU cost it debited. Status transitions stream live as events while the run is in flight, and every run emits an OpenTelemetry trace span (ops.execute) tagged with triform.circle, triform.element, and triform.operation, so a single invocation is findable in SigNoz long after it finishes.

Before the work dispatches, the runtime checks the caller’s capability for that operation — the per-operation auth level it requires — and fails closed when the credential is absent or insufficient. Execution and authorization are the same path: a run that should not happen never reaches its substrate.

Where the runtime lives

The runtime is the triform-physics service (port 3000), organized into force-provider subsystems under physics/src/infra/ — storage, compute/vmm, messaging, auth, crypto, the LLM gateway, network, and search. You do not call those directly; the executor routes each run to the subsystem its operation needs. The Physics overview lists the full subsystem set; this page is about the one path they all hang off.

Related

• Concept: runs — the execution model end to end (the teaching home)
• Pillar: Capabilities — what the runtime checks before it runs an operation
• Pillar: Isolation — the substrate for untrusted code
• Pillar: Live events — watching a run move in real time
• Pillar: Billing — what a run debits