Download all docs

Physics: the runtime

Physics is the layer that runs. Chemistry declares what an element is; the Portal shows it to you; Physics is the Rust process that actually executes an operation, holds the data, enforces the boundary, and bills the work. When you POST to an operation URL, you are talking to Physics. This page is the reference entry to that runtime — what it is made of, and which concept explains each part.

What Physics is

Physics is a single Axum + Tower service (the triform-physics / triform-server crate, port 3000) fronting everything the platform can do. It is mechanism, not policy: it never branches on a specific element type. Every operation flows through one generated dispatch path that reads the element’s category metadata, so the same handler runs a Python action, a SQL query, an LLM call, and a circle creation alike. That element-agnostic contract is the spine of the whole platform — the behaviour lives in Chemistry’s YAML and flows through generated code; Physics is the engine that consumes it.

The operation executor

The unit of work is a run: a POST to /api/{circle}/{slug}/ops/{op} that the executor validates against the operation’s declared input schema, dispatches to the right substrate, and records with inputs, status, output, logs, and a cost debit. One uniform envelope wraps very different machinery underneath — code in a sandbox, a query in Postgres, a call to a model provider. The execution model, and what a run carries after the fact, is its own concept.

→ Concept: runs

Infrastructure subsystems

The runtime is organized into force-provider subsystems under physics/src/infra/, each owning one capability the executor dispatches to:

  • storage — Postgres (per-circle schemas), Git (per-circle element history), and S3-compatible object storage for blobs.
  • compute/vmm — Firecracker microVM lifecycle for sandboxed code execution.
  • messaging — NATS JetStream plus a tiered cache for events and coordination.
  • auth — JWT, OAuth, the EUDI wallet, TFID, MFA, and API keys.
  • crypto — the secret vault and AES-256-GCM encryption.
  • llm — the in-process gateway that fronts multiple model providers behind one interface.
  • network — DNS, TLS/ACME certificate issuance, SMTP, and SSH.
  • search — Tantivy BM25 full-text search.
  • platform — bootstrap, the activity log, and the evaluator loop.

You do not call these directly; the executor routes each run to the subsystem its operation needs. The reference catalog of which capabilities exist, and which operations a given element exposes, is generated from Chemistry — see the Chemistry pillar for how that catalog is produced.

The boundaries Physics enforces

Three guarantees are structural in the runtime, not bolted on:

  • Tenancy. Every circle is its own Postgres schema (circle_{uuid}); a query runs against one circle’s schema and there is no shared table to leak across. The airtight boundary is a fact of where the data lives. → Concept: tenancy-airtight
  • Isolation. Untrusted code (the actions category) runs in a Firecracker microVM with zero internet egress — it can compute but cannot phone home. → Concept: isolation
  • Access. Who may call an operation, and on what terms, is decided by the auth layer and attached modifier policies, default-deny for anything not granted. → Concept: auth

Billing, federation, and live events

The runtime also owns three cross-cutting behaviours, each with its own concept page in LEARN — Physics implements them; it does not re-explain them here:

  • Billing. A metered run debits AU from the circle’s wallet when it executes; no run, no charge. → Concept: billing-au
  • Federation. Relating circles across the airtight boundary — circle-ref resolves another circle, external-agent records an outside peer, and trust grants govern cross-circle traffic. → Concept: federation
  • Live events. Every run’s status transitions stream out in real time, so you can watch work move rather than poll for it. → Concept: live-events

Observability

Every run emits an OpenTelemetry trace span tagged with triform.circle, triform.element, and triform.operation, exported via OTLP to SigNoz. That is the durable record of what one invocation did, how long it took, and where it failed — the same tags you filter on to debug a run after the fact.

Where to go next

  • The capabilities catalog and per-element operations are generated reference — see the Chemistry pillar.
  • The runtime has no UI of its own; the Portal pillar is the interface onto it.
  • Start with runs if you want the single concept that ties the runtime together.