Launch handoff

Quake AI launch handoff lets you declare what you want to run (runtime, environments, resources, optional services) in a versioned quake.yaml file. Quake AI validates that manifest and emits a downloadable handoff packet. The packet is self-contained: an agent with OpenTofu, Docker, and Quake AI credentials can execute it directly, or a human operator or the cloud control plane can run the same steps.

This platform validates intent and assembles references. It does not run builds, push container images, provision preview URLs, or enforce preview TTL on your behalf.

What you author#

Place quake.yaml at the root of your application repository. The file uses schema version 1 and declares:

• Application identity (name, runtime)
• How source is built (source.build, optional dockerfile path)
• One or more named environments (production, preview, or custom keys) with branch rules, flavor aliases, optional domain, and optional preview TTL
• Optional backing services (for example object storage) mapped to IaC templates
• Secret names only (never values)
• Whether to attach an evidence bundle stub (evidence: true)

Field names, enum values, and resolution rules are documented on the quake.yaml reference page. Machine-readable JSON Schema is published at https://docs.quake.ai/schema/quake-manifest.v1.json.

Branch-to-environment workflow#

Typical git workflow maps branches to environments declared in the manifest:

The manifest records branch rules and flavor aliases. The control plane (or a human following the handoff packet) maps the git revision to the correct environment entry, applies the resolved IaC templates, and runs the container or VM workload.

Preview environments often set ttl_hours (for example 72). The manifest carries that value as advisory metadata; teardown scheduling lives on the control plane.

Handoff model#

1. Author quake.yaml in your repo (or ask your IDE agent to draft it from the reference page).
2. Validate by calling the validate_launch_manifest MCP tool with the parsed manifest JSON. Fix schema, flavor, or template resolution errors before continuing.
3. Prepare by calling prepare_launch with the manifest and an action (deploy, preview, promote, or rollback). On success you receive a PortableArtifact whose JSON content is the handoff packet plus a Markdown preview for humans.
4. Execute the packet. An agent or operator runs resolved.build.steps to produce the image, applies the templates in resolved.template_plan order (binding the resolved variables and container_env), and reads the runtime outputs to verify. DNS, TLS, and managed preview URLs happen outside this documentation platform.

Tool inputs, response shapes, and artifact types are documented in the AI tools reference.

Handoff packet contents#

A successful prepare_launch call returns JSON content with these top-level fields:

The resolved block carries everything a consumer needs to execute without re-deriving it:

The prepare_launch action selects which environment entry is resolved:

If the manifest omits the required environment, validation fails and no packet is emitted.

Evidence bundle#

When evidence: true (or by default for prepared launches), the packet includes an evidence bundle attachment. At handoff time the bundle is a pending stub: deploy id, build logs, IaC plan output, preview URL, and gate results are null or pending. The control plane fills those fields after it runs build, apply, and health checks.

Every stub includes validation gate rows for at least:

• no-leaked-secrets
• health-check
• manifest-schema
• iac-template-resolved

Gate statuses start as pending. A consumer updates them to pass, fail, warn, or skip as work completes.

Runtime and template resolution#

Optional services[] entries resolve to additional templates and apply before the runtime so it can consume their outputs:

Each service entry's provides lists its outputs (for example a Postgres private_ip and database_url); the runtime entry's depends_on names the service template slugs, and its consumes references the outputs it wires in. Passwords stay name-only: declare them in secrets and supply the value out of band. The supabase type resolves to the supabase-selfhost template, the full BaaS stack on a single instance; see the Supabase self-host deployment for a step-by-step build. See the containerized app template for how runtime: container maps to OpenTofu parameters, and the quake.yaml services reference for the full resolution table.

Flavor aliases#

Environment resources fields use aliases, not raw flavor names:

Validation resolves aliases against the production flavor catalog. Use cpu-standard for production-sized workloads and cpu-small for preview defaults.

What this platform does not do#

The launch handoff surface stops at the packet download. Out of scope for this documentation platform:

• Running Dockerfile or buildpack builds
• Pushing images to a registry
• SSH or remote exec on instances
• Assigning preview URLs, TLS certificates, or DNS records
• Enforcing preview TTL timers
• Persisting evidence to object storage

The agent or operator executing the packet handles those steps using resolved.build, resolved.template_plan, and next_steps. A managed control plane handles them for the non-agent path.

See also#

• quake.yaml reference: every v1 field, enum, and constraint
• AI tools reference: validate_launch_manifest and prepare_launch MCP tools
• Containerized app template: golden-path mapping for runtime: container
• Automation templates index: IaC library referenced by services and runtime resolution