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.

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

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.
`source`	object	yes	Build source declaration. See Source.
`environments`	object	yes	Named environment configs. At least one entry required. See Environments.
`services`	array	no	Optional backing services. See Services.
`secrets`	array	no	Secret variable names only. See 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` template
`audio-worker`	accepted	Resolves to the `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`	`<NAME>_BUCKET_NAME`, `<NAME>_BUCKET_ARN`
`postgres`	`self-managed-postgres`	`<NAME>_DATABASE_URL`
`mysql`	`mysql-database`	`<NAME>_DATABASE_URL`
`redis`	`redis-cache`	`<NAME>_REDIS_URL`
`vector`	`qdrant`	`<NAME>_QDRANT_URL`
`analytics`	`analytics-umami`	`<NAME>_ANALYTICS_URL`
`inference-gateway`	`inference-gateway`	`<NAME>_GATEWAY_URL`
`supabase`	`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. 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 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.

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:

Schema: all required fields, literal version: 1, regex constraints on name, service names, and secret names
Source cross-field rule: dockerfile required when source.build is dockerfile
Environments: at least one entry; each resources value is a known flavor alias
Services: each type maps to a known IaC template slug
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 for packet field descriptions and AI tools reference for MCP request and response shapes.

quake.yaml reference