Skip to Content
Platform
PlatformOperating runtimes

Operating runtimes

The procedures around a runtime’s lifecycle: bootstrap, lane control, withdrawal, and what actually happens when a managed task starts.

This page assumes the runtime concept — groups, lanes, and the three senses of pinning — and the manifest reference.

Use the dashboard or CLI to register runtimes, choose what staging serves, or withdraw a bad version. Application SDKs resolve runtimes and start tasks; they do not change deployment state.

Bootstrap the first version

The first introspection runtimes create --manifest ... records an immutable recipe pin and creates the runtime group.

Creating the first runtime is a production bootstrap, not a staging preview. Run runtimes create from a clean, pushed main branch. The first version immediately becomes active in both staging and production. A feature branch or pull-request commit cannot bootstrap a staging-only runtime.

If the recipe begins on a feature branch, review and merge that pull request first. Then check out the resulting main commit and create the runtime from there. After the runtime group exists, pull-request commits can produce candidate versions for staging while production continues to follow main.

Control what staging serves

Staging can follow a Git branch or pull request, or be pinned to one exact commit. A lane that follows a moving ref advances when a new runtime version is built from that ref. Pinning a commit freezes the lane on that immutable version; introspection runtimes unpin returns staging to main.

Unpinned production advances with the repository’s default branch. The CLI and dashboard expose the lane controls for staging; pinning production is a Control Plane API operation.

Runtime versions themselves never change. Moving or pinning a lane only changes which immutable version receives new work. development remains the local introspection dev lane.

Follow the Agent development lifecycle to register a recipe and test it in staging. See CLI → Runtimes for every runtime command.

Yank a bad version

If a version turns out to be bad, yank it. A yanked runtime stops accepting new tasks while existing tasks keep their pinned version. You can reverse the decision by unyanking it. Use introspection runtimes update --yank / --unyank or the dashboard.

Yanking withdraws one immutable version from new work; it does not move a lane or rebuild anything. If the lane was following a ref, it advances normally when the fixed commit lands.

How a managed task starts

Each managed task uses one recipe version from start to finish. Introspection loads the registered recipe path at the Git commit selected for the task’s environment. Moving an environment to another version affects new tasks, not a task that is already running.

Before the agent starts, Introspection:

  1. Loads the recipe source. Only the registered recipe path at the pinned commit is included.
  2. Prepares the recipe. Paths matched by the root .recipeignore are excluded. Declared production dependencies are installed or validated, and requested system capabilities are checked.
  3. Resolves the agent. The runtime resolves the recipe’s agent definitions and uses the agent configured for the task.
  4. Makes task resources available. These can include recipe-provided files, restored task files, uploads, skills, memory, and environment bindings.
  5. Starts the agent. The task begins only after the recipe and its required resources are ready.

Runtime reads show image preparation as pending, queued, building, ready, or failed. A failed build includes an error and may include a log file. A completed image may also report its size.

Keep agent behavior, dependency declarations, skills, extensions, and other portable configuration in the recipe. Keep concrete secrets and endpoint URLs in environment bindings rather than recipe source.

Cloud validation distinguishes a recipe defect from a validation attempt that could not finish. An invalid recipe includes file diagnostics and cannot start a managed task. A failed validation includes an error message. The dashboard can request a fresh validation attempt; completed results are otherwise owned by the validation service.

Recipe dependencies

Node dependencies use the recipe’s ordinary package.json#dependencies. The managed runtime discovers the recipe root and nested packages, installs production dependencies with pnpm into a hoisted node_modules, and links the Pi peers already supplied by the runtime image. devDependencies stay authoring-only and are not installed in the sandbox.

A recipe declares Python and system requirements under pi.runtime. The managed runtime satisfies them while preparing the recipe workspace, before the first model call.

For a declared Python project, the runtime:

  1. verifies that pyproject.toml and uv.lock are inside the recipe;
  2. runs a frozen production install into .pi/python;
  3. reuses that environment while the project and lockfile digest is unchanged;
  4. runs any declared import preflights;
  5. activates the environment for Pi and recipe-owned processes through VIRTUAL_ENV and PATH.

The install never modifies system Python, includes development dependencies, or resolves a newer dependency graph than the committed lock. A missing lock, incompatible interpreter, failed install, or failed import stops the runtime before the agent starts.

System requirements use versioned capability IDs such as document.pdf-tools@1. These map to reviewed software already present in the runtime image. Recipes cannot execute apt-get, Homebrew, or arbitrary privileged boot scripts. If the image does not advertise a requested capability and version, the runtime fails closed with an actionable error.

Files and task artifacts

Files in the recipe’s conventional files/ directory become read-only task inputs alongside restored task files and conversation uploads. Nested paths and binary contents, such as spreadsheets, are preserved. A recipe file cannot replace a file already restored into the task workspace. Conversation uploads are materialized after restored task files, so use distinct paths when both sources may contain the same filename. Files the agent creates or changes are versioned through the Files API at checkpoints and task completion. See Packaging a recipe for limits and authoring guidance.

What can prevent startup

Introspection does not start the agent when the registered commit or recipe path cannot be loaded, the recipe or configured agent is invalid, or a declared dependency or system requirement cannot be satisfied. Startup also fails when recipe-provided files exceed their limits, contain symlinks, or collide with a restored task file or upload. Correct the recipe version or required environment configuration before starting another task.

Last updated on