# quake.yaml reference

Source: https://docs.quake.ai/resources/ai-assisted-development/quake-yaml
Markdown: https://docs.quake.ai/resources/ai-assisted-development/quake-yaml.md
> Reference for quake.yaml manifest version 1: top-level fields, enum values, environment rules, service and secret constraints, and flavor or template resolution.

---

# Quake.yaml reference

`quake.yaml` is the version `1` launch manifest format. It declares application launch intent: runtime, build source, environments, optional services, and secret names. Validation runs through the `validate_launch_manifest` MCP tool or the `prepare_launch` tool before a handoff packet is emitted.

For workflow context (branch mapping, handoff model, evidence bundle), see [Launch handoff](/resources/ai-assisted-development/launch).

JSON Schema (draft 2020-12): [`https://docs.quake.ai/schema/quake-manifest.v1.json`](https://docs.quake.ai/schema/quake-manifest.v1.json)



The launch-handoff resolves application workloads: the `runtime` value and any `services` you declare. The standalone infrastructure templates in the library (VM, private network, edge reverse proxy, Kubernetes, Heat stack, monitoring) sit outside the launch-handoff. Fetch them with [`get_template`](/resources/ai-assisted-development/ai-tools-reference#get_template) and apply them directly with OpenTofu or Heat. Browse the full set in the [IaC template library](/resources/iac-templates).



## Example manifest

```yaml
version: 1
name: my-app
runtime: container
source:
  build: dockerfile
  dockerfile: ./Dockerfile
environments:
  production:
    branch: main
    resources: cpu-standard
    domain: my-app.example
  preview:
    branch: "*"
    resources: cpu-small
    ttl_hours: 72
services:
  - type: object-storage
    name: assets
secrets:
  - DATABASE_URL
evidence: true
```

## Top-level fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `version` | `1` (literal) | yes | Schema version. Only `1` is accepted today. |
| `name` | string | yes | Application id. Lowercase kebab-case starting with a letter (`^[a-z][a-z0-9-]*$`). |
| `runtime` | enum | yes | `container`, `audio-worker`, or `gpu`. See [Runtime](#runtime). |
| `source` | object | yes | Build source declaration. See [Source](#source). |
| `environments` | object | yes | Named environment configs. At least one entry required. See [Environments](#environments). |
| `services` | array | no | Optional backing services. See [Services](#services). |
| `secrets` | array | no | Secret variable names only. See [Secrets](#secrets). |
| `evidence` | boolean | no | When true, handoff packets include an evidence bundle stub. |

## Runtime

| Value | Validation | Template resolution |
| --- | --- | --- |
| `container` | accepted | Resolves to the [`containerized-app`](/resources/iac-templates/containerized-app) template |
| `audio-worker` | accepted | Resolves to the [`audio-worker`](/resources/iac-templates/audio-worker) template (a VM with cloud-init; no container image build) |
| `gpu` | accepted with **warning** | No template resolution in this release. Message: `runtime: gpu is reserved for a future Northern Data lane; the POC validates the enum only.` |

## Source

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `build` | enum | yes | `dockerfile` or `buildpack` |
| `dockerfile` | string | conditional | Required when `build` is `dockerfile`. Path to the Dockerfile relative to the repo root. |

When `build` is `buildpack`, omit `dockerfile`. The enum is validated; `buildpack` execution is outside this platform.

## Environments

`environments` is a map of environment name to config object. Keys are free-form strings (for example `production`, `preview`). Validation requires at least one entry.

Each environment object:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `branch` | string | yes | Git branch rule. Use an exact name (`main`) or `"*"` for any non-matching branch. |
| `resources` | enum | yes | Flavor alias: `cpu-standard` or `cpu-small`. |
| `domain` | string | no | Optional hostname hint for the control plane. |
| `ttl_hours` | integer | no | Positive integer. Advisory preview lifetime in hours. |

### Flavor alias resolution

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

Aliases map to names in the production flavor catalog. Invalid alias values fail validation with an actionable error path.

### Action-to-environment requirements

The `prepare_launch` MCP tool maps actions to environment keys:

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

## Services

Optional array of backing service declarations.

Each service object:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | enum | yes | `object-storage`, `postgres`, `mysql`, `redis`, `vector`, `analytics`, `inference-gateway`, or `supabase` |
| `name` | string | yes | Service instance name. Lowercase kebab-case starting with a letter. |

### Service type resolution

| `type` value | Template | App-facing output |
| --- | --- | --- |
| `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` |

`<NAME>` is the service `name` upper-cased with hyphens replaced by underscores (for example a service named `primary-db` contributes `PRIMARY_DB_DATABASE_URL`). The handoff packet lists these keys in each runtime entry's `container_env` with a null value; the consumer assembles the connection string from the service's `private_ip` output and the password you supply as a [secret](#secrets). For `inference-gateway`, the consumer reads `gateway_url` directly. For `analytics`, the consumer reads `dashboard_url`. For `supabase`, the consumer reads `api_url` and pairs it with the anon and service_role keys generated on the instance. Unknown `type` values fail validation.

The `supabase` type resolves to the [`supabase-selfhost`](/resources/iac-templates/supabase-selfhost) template, the full BaaS stack (Postgres, Auth, Storage, real-time channels, and Studio) on a single instance. For a step-by-step build, follow the [Supabase self-host deployment](/resources/deployments/deploy-supabase-selfhost-template).

## Secrets

Optional array of strings. Each entry is a secret **name**, never a value.

| Constraint | Rule |
| --- | --- |
| Format | `UPPER_SNAKE_CASE` environment variable name (`^[A-Z][A-Z0-9_]*$`) |
| Values | Must not appear in `quake.yaml`. Inject values through the control plane or runtime secret store. |

## Evidence

| Field | Type | Description |
| --- | --- | --- |
| `evidence` | boolean | When true (recommended for auditable launches), `prepare_launch` attaches a pending evidence bundle stub to the handoff packet. |

The stub includes gate rows (`no-leaked-secrets`, `health-check`, `manifest-schema`, `iac-template-resolved`) with status `pending`. Runtime fields (`deploy_id`, build log URL, preview URL, IaC plan text) are null until the control plane fills them.

## Validation rules summary

Validation (via MCP or unit tests) checks:

1. **Schema:** all required fields, literal `version: 1`, regex constraints on `name`, service names, and secret names
2. **Source cross-field rule:** `dockerfile` required when `source.build` is `dockerfile`
3. **Environments:** at least one entry; each `resources` value is a known flavor alias
4. **Services:** each `type` maps to a known IaC template slug
5. **Runtime:** `gpu` produces a warning, not a hard error

On success, `validate_launch_manifest` returns `valid: true` plus a `resolved` block listing runtime template path, per-environment flavor names, and service template paths.

## Handoff packet cross-reference

After validation, call `prepare_launch` with:

| Parameter | Type | Description |
| --- | --- | --- |
| `manifest` | object | Parsed manifest JSON (convert YAML to JSON before calling) |
| `action` | enum | `deploy`, `preview`, `promote`, or `rollback` |
| `source_sha` | string | Optional git commit SHA |

Successful responses wrap a handoff packet in a `PortableArtifact` with `artifact_type: launch_handoff`. See [Launch handoff](/resources/ai-assisted-development/launch) for packet field descriptions and [AI tools reference](/resources/ai-assisted-development/ai-tools-reference) for MCP request and response shapes.

## See also

- [Launch handoff](/resources/ai-assisted-development/launch): workflow, branch mapping, and manual consumer steps
- [AI tools reference](/resources/ai-assisted-development/ai-tools-reference): MCP tool parameters
- [Containerized app template](/resources/iac-templates/containerized-app): `runtime: container` golden path