Skip to Content
Platform
Core ConceptsDeploying a recipe

Deploying a recipe

How a Git-backed recipe becomes a deployable runtime: the manifest that declares it, the GitHub integration it needs, and how each commit flows into staging and production.

A recipe is behavior in Git; a runtime is that behavior made deployable. Deploying is the bridge between them. You declare a manifest in the repository, connect the repository through your organization’s GitHub integration, and Introspection pins the exact commit and builds a runtime version from it.

The manifest

The .introspection/<name>.yaml file is the repository-level declaration that connects a recipe package to its runtime defaults. Its filename is the stable runtime-group slug, so later commits become new versions of the same logical agent rather than unrelated runtimes.

.introspection/support-agent.yaml
name: support-agent
description: Triage support requests, draft grounded replies, and escalate sensitive cases.
path: .
runtime:
  llm_mode: managed

The manifest declares:

KeyWhat it declares
nameThe runtime-group name. Must equal the filename stem — support-agent here matches support-agent.yaml.
slugURL-safe group id; defaults to name.
runtime_nameOptional display name for the runtime.
pathSub-path to the recipe package within the repository. Defaults to . (the repo root).
descriptionA short summary of what the recipe does. Omitting it is a warning, not an error.
includesExtra file globs to pull into the recipe workspace.
runtime.llm_modeHow the runtime gets LLM credentials: managed (default, platform-supplied) or byok (your own, via bindings).
runtime.resourcesSandbox sizing as Kubernetes requests/limits (cpu, memory, storage). Advisory upward request — the platform clamps to its deployment minimum.
strictWhen true, unknown manifest keys are errors instead of warnings. Defaults to false.

The filename stem and name must match. support-agent.yaml with name: support fails validation with a filename-mismatch error. Rename the file or the field so they agree — the name is the group’s stable identity across every future version.

Validate the manifest, package metadata, and every declared agent, skill, and glob offline before you deploy:

introspection recipes validate
introspection recipes validate --path .introspection/support-agent.yaml

Validation exits 0 on success; errors exit 1, and warnings alone do not fail it.

Your repository must be under the organization’s GitHub integration

Deployment is Git-native: Introspection pins commits from a repository it can read through your organization’s GitHub integration. A repository that isn’t connected to that integration cannot be pinned. runtimes create fails with Active GitHub integration not found, and a repository row with no integration reports Recipe repository has no GitHub integration. A personal fork that the integration doesn’t cover produces the same failure — connect the repository through the org integration first.

Bootstrapping a runtime also needs a clean checkout of pushed main. Confirm it before you start:

git status --short
git rev-parse HEAD origin/main

HEAD must equal origin/main and the working tree must be clean; otherwise the pin would reference a commit the integration can’t see.

From manifest to runtime

With the repository connected and the checkout clean, create the runtime from the manifest:

introspection runtimes create --manifest .introspection/support-agent.yaml

This validates the workspace, creates the immutable recipe pin (repository, Git ref, commit SHA, and the manifest’s sub-path), and bootstraps the first runtime version in a new runtime group. The response carries the new version’s id, runtime_group_id, and recipe_id.

Bootstrap immediately activates that first version for both production and staging. Treat runtimes create as a production deployment, not a staging-only preparation step. Verify the returned runtime’s environments before sending traffic. Later pull-request versions do not move production; production changes when the integrated repository processes main.

The runtime image builds asynchronously. You can watch image_status move pending → ready with introspection runtimes get <runtime-id>, but you do not need to wait for ready to start a task — the sandbox builds on demand, so a pending version can still serve. A failed status means the build errored and the response explains why.

Versions and environments

Every commit the integration processes becomes a new immutable version in the same runtime group — the manifest filename is what keeps them in one lineage. Which version serves a request is decided by the environment lane it lands in:

  • staging tracks a branch or PR ref, so it advances as new versions arrive. Pin it to freeze one exact version for a controlled test (introspection runtimes staging track / staging pin).
  • production is moved by a merge to main: the integration creates the immutable version and activates it for production. There is no CLI promote — shipping is the merge, which keeps “what’s live” auditable.
  • development is the local iteration lane used by introspection dev.

A task selects its lane with --environment on the CLI, or through the environment its API key is scoped to in the SDK; the active version for that lane answers. Normal end-user work targets production; staging and development drive the pre-production lanes.

Managed vs bring-your-own

By default (llm_mode: managed) the platform supplies model credentials, so a recipe with no external dependencies deploys with nothing else to configure. Set llm_mode: byok to bring your own provider key, supplied out of band as a credential referenced from an endpoint header — the value is applied at the egress boundary and never reaches the sandbox. Any external endpoints, variables, and MCP servers the recipe declares are connected the same way, per environment. See Bindings and LLM providers.

Last updated on