How PAL Runtime works

PAL Runtime is split into a control plane that decides and runtime services that do the work. The control plane authenticates the caller, checks budgets, stores state and talks to the model providers. The workflow engine drives runs step by step, and the scheduler, runtime-manager and harness place and run untrusted code in microVMs. You write an agent and call one API; the split below decides where each part of the run happens.

SystemRuntime managerHarnessTrust boundariesData storesControl / data planeGuest egress (default)Broker mode (opt-in)

Swipe sideways to pan the diagram. Tap a component for details.

Click a component for what it does, its port, the trust boundary it enforces, and the code. Runtime manager and harness open into component views.

• Trusted host code
• Untrusted guest code
• The microVM wall
• A gate: what a caller must present

Who does what

	Your code	The control plane	The runtime services
Owns	The agent definition, prompts, tools, input	Auth, tenants, budgets, agents, runs, sessions, provider keys	Run state (workflow engine), VM placement and lifecycle (scheduler, manager)
Runs	Inside a microVM, if you declare isolation: microvm	Shared-tier runs and the model-call path. Never user code in a microVM	Durable steps, model routing, VM spawn, egress enforcement
Sees	Its input and the secrets it is vended	Every request, tagged with tenant_id	Only its own tenant’s runs, checked on every call

Three rules hold the split together. The control plane never touches code in a microVM; only the runtime-manager does. The workflow engine is the only writer of run state. Models are addressed by capability, so the router, not your agent, picks the vendor model.

How a request travels

1. The gateway authenticates. A client sends POST /v1/runs with an API key (X-API-Key or Authorization: Bearer). The gateway terminates TLS, validates the key with the control plane, applies rate limits and forwards to the control plane.
2. The control plane admits the run. It resolves the agent version, reads manifest.isolation, and checks the budget. A reached hard-fail limit returns 402 here, before any model call.
3. The run executes. On the shared tier the control plane’s executor drives it. On the microVM tier it asks the scheduler for a node, and the runtime-manager spawns the VM.
4. Model calls go out by capability. model: "auto" or reasoning-large is mapped to a concrete model. See Models and routing.
5. Every step is journaled to journal_events before it runs. A crash resumes from the journal (Durable execution).
6. Events stream back to the caller over SSE, with no full-response buffering in between (Streaming).

The step-by-step version with failure paths is Request lifecycle.

What runs where

Service	Language	Port	Role
gateway	Rust	:8443	TLS, API-key auth (no session JWTs; the dashboard talks to the control plane), rate limits, SSE proxy
control-plane	Go	:8080 REST, :50051 gRPC	API, budgets, agents, runs, sessions; never touches user code
workflow-engine	Go	:50052	Durable event-sourced steps; the only writer of run state
model-router	Rust	:50053	Capability addressing, 4 strategies, cache, failover
runtime-manager	Rust	:50054	VM lifecycle on a node; egress broker in broker mode
runtime-scheduler	Go	:50055 gRPC, :8085 REST	Placement and leader election
surface-gateway	Rust	:8444	Inbound channel webhooks
harness	Rust	PID 1 in the VM	Heartbeats, secrets socket, egress, tool runner

The model-router service is off by default for the control plane’s own completions (PAL_USE_MODEL_ROUTER); see Models and routing.

Go deeper

Request lifecycle, microVM lifecycle, Security boundaries, Durability, Deployment topology, PAL internals.