---

title: 'YAML syntax for Spicepod manifests' sidebar_position: 1 sidebar_label: 'Spicepod specification' description: 'Detailed documentation on the Spicepod manifest syntax (spicepod.yaml)' tags:

• reference
• spicepod
• yaml
• manifest

---

Spicepod manifests use YAML syntax. By default they are stored in the root directory of the application and named spicepod.yaml or spicepod.yml — when the runtime is given a directory path, it looks for one of those two filenames. The runtime also accepts any YAML file path directly (e.g. spiced ./configs/my-app.yaml); files passed by path must declare kind: Spicepod and a recognized version and are otherwise rejected with an explicit error.

:::info[Tip]

Readers who are new to YAML can find a primer in "Learn YAML in Y minutes."

:::

version

The version of the Spicepod manifest. The current version is v2.

kind

The kind of Spicepod manifest. The kind is Spicepod.

name

The name of the Spicepod.

secrets

The secrets section in the Spicepod manifest is optional and is used to configure how secrets are stored and accessed by the Spicepod. For more information, see Secret Stores.

secrets.from

The from field is a string that represents the Uniform Resource Identifier (URI) for the secret store. This URI is composed of two parts: a prefix indicating the Secret Store to use, and an optional selector that specifies the secret to retrieve.

The syntax for the from field is as follows:

Where:

• <secret_store>: The Secret Store to use

  Currently supported secret stores:

  • env
  • kubernetes
  • keyring
  • aws-secrets-manager

  If no secret stores are explicitly specified, it defaults to env.

• <selector>: The secret within the secret store to load.

The type of secret store for reading secrets.

Example

secrets.name

The name of the secret store. This is used to reference the store in the secret replacement syntax, ${<secret_store_name>:<key_name>}.

runtime

The runtime section specifies configuration settings for the Spice runtime. For detailed documentation, see the Runtime YAML reference.

metadata

An optional map of metadata.

Example

datasets

A Spicepod can contain one or more datasets referenced by relative path.

Example

A datasets referenced by relative path.

A dataset defined inline.

snapshots {#snapshots}

Optional. Configure managed acceleration snapshots that Spice can use to bootstrap file-based accelerations. When enabled, datasets that opt in with acceleration.snapshots will download database files from the snapshot location if the local file is missing, and will optionally write new snapshots after each refresh. DuckDB, SQLite, Cayenne, and Turso accelerations running in mode: file are supported, and each dataset must write to its own file path.

snapshots.enabled

Enable or disable snapshot management globally. Defaults to true.

snapshots.location

The folder where snapshots are stored. Supports S3 bucket URIs (s3://bucket/prefix/), Azure ADLS Gen2 URIs (abfss://container@account.dfs.core.windows.net/path/), Google Cloud Storage URIs (gs://bucket/prefix/), and absolute or relative filesystem paths. The path must resolve to a single folder; Spice creates per-dataset folders underneath using Hive-style partitions (month=YYYY-MM/day=YYYY-MM-DD/dataset=<name>).

snapshots.bootstrap_on_failure_behavior

Controls what happens when Spice cannot load the most recent snapshot on startup. Valid values:

• warn (default) – Log a warning and continue with an empty acceleration.
• retry – Retry the newest snapshot until it loads successfully.
• fallback – Attempt older snapshots in the same dataset folder until one works.

snapshots.params

Optional key-value map passed to the snapshot storage layer. When location points to S3, the configuration accepts any of the S3 dataset parameters. Snapshots default to s3_auth: iam_role, which differs from the S3 dataset default of public. Azure ADLS and GCS locations also accept their respective connector parameters for explicit credential overrides; when no overrides are supplied, Spice reads standard environment variables for each cloud provider.

models

A Spicepod can contain one or more models referenced by relative path.

Example

A model referenced by path.

A model defined inline.

embeddings

A Spicepod can contain one or more embeddings referenced by relative path.

Example

An embeddings model referenced by path.

An embedding defined inline.

dependencies

A list of dependent Spicepods.

views {#views}

A Spicepod can contain one or more views which are virtual tables defined by SQL queries.

Example

workers

A Spicepod can contain one or more workers defining configurable units of compute.

Example

For a complete specification of worker configuration, see the Workers Reference.