# Launch handoff

Source: https://docs.quake.ai/resources/ai-assisted-development/launch
Markdown: https://docs.quake.ai/resources/ai-assisted-development/launch.md
> Declare application launch intent in quake.yaml, validate it through the MCP server, and download a handoff packet for a human or control-plane consumer to execute.

---

# 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](/resources/ai-assisted-development/quake-yaml) page. Machine-readable JSON Schema is published at [`https://docs.quake.ai/schema/quake-manifest.v1.json`](https://docs.quake.ai/schema/quake-manifest.v1.json).

## Branch-to-environment workflow

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

| Git event | Environment | Launch action |
| --- | --- | --- |
| Push a feature branch or open a pull request | `preview` (branch pattern such as `"*"`) | `preview` |
| Merge to `main` | `production` (`branch: main`) | `deploy` or `promote` |
| Revert a bad production deploy | `production` | `rollback` |

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

<Figure caption="Launch handoff flow: the agent authors quake.yaml, the MCP server validates and prepares a packet, and a consumer executes the packet.">

```mermaid
flowchart LR
  accTitle: Quake AI launch handoff flow
  accDescr: An IDE agent authors quake.yaml, calls MCP validate and prepare tools, receives a handoff packet, and an agent or operator executes build and deploy outside this platform.

  agent["Agent in IDE"]
  manifest["quake.yaml"]
  mcp["MCP server"]
  packet["Handoff packet"]
  consumer["Agent or operator"]

  agent --> manifest
  manifest --> mcp
  mcp --> packet
  packet --> consumer
```

</Figure>

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](/resources/ai-assisted-development/ai-tools-reference).

## Handoff packet contents

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

| Field | Description |
| --- | --- |
| `request_id` | Stable id with `lreq_` prefix (for example `lreq_20260618-a1b2c3d4e5f6`) |
| `action` | `deploy`, `preview`, `promote`, or `rollback` |
| `created` | ISO 8601 timestamp when the packet was generated |
| `source_sha` | Optional git commit SHA you supplied |
| `manifest` | Normalized manifest after validation |
| `resolved` | Target environment, flavor alias, IaC template paths, preview `ttl_hours`, plus `build` and `template_plan` (see below) |
| `evidence_bundle` | Pending stub (see below) |
| `next_steps` | Step-by-step instructions for the consumer (agent or operator) |

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

| `resolved` field | Description |
| --- | --- |
| `build` | Build recipe: `method`, `dockerfile`, `steps` (build, push, set `container_image`), and the `<registry>` placeholder to replace |
| `template_plan` | Ordered apply plan. Services apply before the runtime. Each entry lists `variables` (with `value: null` where you supply it), `container_env`, `provides` (outputs), `consumes`, and `depends_on` |

The `prepare_launch` action selects which environment entry is resolved:

| Action | Required environment key |
| --- | --- |
| `preview` | `preview` |
| `deploy`, `promote`, `rollback` | `production` |

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

| `runtime` value | Resolved IaC template | Notes |
| --- | --- | --- |
| `container` | [`containerized-app`](/resources/iac-templates/containerized-app) | Golden-path CPU VM plus Docker lane |
| `gpu` | (none) | Enum accepted; validation emits a warning only |

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

| `services[].type` | Resolved IaC template | App-facing `container_env` key |
| --- | --- | --- |
| `object-storage` | [`s3-storage-acl`](/resources/iac-templates/s3-storage-acl) | `<NAME>_BUCKET_NAME`, `<NAME>_BUCKET_ARN` |
| `postgres` | [`self-managed-postgres`](/resources/iac-templates/self-managed-postgres) | `<NAME>_DATABASE_URL` |
| `mysql` | [`mysql-database`](/resources/iac-templates/mysql-database) | `<NAME>_DATABASE_URL` |
| `redis` | [`redis-cache`](/resources/iac-templates/redis-cache) | `<NAME>_REDIS_URL` |
| `vector` | [`qdrant`](/resources/iac-templates/qdrant) | `<NAME>_QDRANT_URL` |
| `analytics` | [`analytics-umami`](/resources/iac-templates/analytics-umami) | `<NAME>_ANALYTICS_URL` |
| `inference-gateway` | [`inference-gateway`](/resources/iac-templates/inference-gateway) | `<NAME>_GATEWAY_URL` |
| `supabase` | [`supabase-selfhost`](/resources/iac-templates/supabase-selfhost) | `<NAME>_SUPABASE_URL` |

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`](/resources/ai-assisted-development/quake-yaml#secrets) and supply the value out of band. The `supabase` type resolves to the [`supabase-selfhost`](/resources/iac-templates/supabase-selfhost) template, the full BaaS stack on a single instance; see the [Supabase self-host deployment](/resources/deployments/deploy-supabase-selfhost-template) for a step-by-step build. See the [containerized app template](/resources/iac-templates/containerized-app) for how `runtime: container` maps to OpenTofu parameters, and the [`quake.yaml` services reference](/resources/ai-assisted-development/quake-yaml#services) for the full resolution table.

## Flavor aliases

Environment `resources` fields use aliases, not raw flavor names:

| Alias | Quake AI flavor |
| --- | --- |
| `cpu-standard` | `m2a.large` |
| `cpu-small` | `s1a.small` |

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](/resources/ai-assisted-development/quake-yaml): every v1 field, enum, and constraint
- [AI tools reference](/resources/ai-assisted-development/ai-tools-reference): `validate_launch_manifest` and `prepare_launch` MCP tools
- [Containerized app template](/resources/iac-templates/containerized-app): golden-path mapping for `runtime: container`
- [Automation templates index](/resources/iac-templates): IaC library referenced by `services` and runtime resolution