Optional app.yml manifest for Snowflake App Runtime¶

The optional app.yml manifest tells Snowflake how to install, build, run, and package your application, along with optional display metadata (profile) and runtime configuration such as environment variables and secrets. When you don’t provide it, Snowflake auto-detects build and run behavior from your project layout (for example, package.json for Node.js). Hand-edit app.yml when you need to customize those install, build, run, or packaging steps, or to set the app’s display profile, environment variables, or secrets. Name the file app.yml and place it in your application source.

For deploy configuration, the Snowflake CLI uses a separate snowflake.yml project file that snow app setup creates and snow app deploy reads. See Getting started with Snowflake App Runtime and snow app setup.

app.yml reference¶

Top-level structure¶

install:
  commands:
    - [<command>, <arg>, ...]
build:
  commands:
    - [<command>, <arg>, ...]
run:
  command: [<command>, <arg>, ...]
artifacts:
  - src: <glob_pattern>
    dest: <destination_path>
profile:
  icon: <relative_path_to_icon>
  label: <display_label>
  description: <description_text>
environment_variables:
  - name: <var_name>
    value: <var_value>
secrets:
  - name: <mount_name>
    secret: <fully_qualified_secret_name>

All top-level keys are optional. Snowflake ignores unknown keys.

Keys¶

install¶

Commands Snowflake runs during the install phase, before the build. Each entry under commands is an argv-style list, passed directly without a shell. Use install for setup steps such as installing dependencies.

install:
  commands:
    - [npm, ci]

build¶

Commands Snowflake runs during the build phase. Each entry under commands is an argv-style list.

build:
  commands:
    - [npm, run, build]

run¶

The entry-point command that starts the application container. command is an argv-style list.

run:
  command: [node, server.js]

artifacts¶

Copy rules that move files produced by the build into the final package. Each entry has these fields:

• src: Glob pattern, relative to the build working directory, that matches the files to copy. The pattern supports ** for recursive matching (provided by the doublestar (https://github.com/bmatcuk/doublestar) library). For example, dist/** matches every file under dist at any depth.
• dest: Destination path within the package. Set dest to . to flatten matched files into the package root by basename. Set dest to any other path to preserve the directory structure of the matched files relative to the glob base, rooted at dest.

Only files that match the glob are copied; directories themselves aren’t copied. To include a directory tree, use **.

artifacts:
  - src: "dist/**"
    dest: "."
  - src: "package.json"
    dest: "."

profile¶

Presentation metadata surfaced alongside the deployed service.

• icon: Relative path to a .png or .svg file inside the package. The path must not contain ...
• label: Short display label.
• description: Longer human-readable description.

The label and description values appear in the additional_properties column of SHOW APPLICATION SERVICES.

profile:
  icon: assets/logo.png
  label: Customer Portal
  description: Web UI for the customer-facing portal.

environment_variables¶

Non-sensitive configuration values that Snowflake exposes as environment variables inside the application container. Each entry has:

• name: Environment variable name.
• value: String value.

environment_variables:
  - name: LOG_LEVEL
    value: "INFO"
  - name: APP_REGION
    value: "us-west-2"

Read them like any other environment variable in your application code:

const logLevel = process.env.LOG_LEVEL ?? "INFO";

import os
log_level = os.getenv("LOG_LEVEL", "INFO")

secrets¶

Snowflake secret objects to make available to the application at runtime. Each entry has:

• name: Mount name used to locate the secret files inside the container.
• secret: Fully qualified name of an existing Snowflake secret (<database>.<schema>.<secret_name>).

secrets:
  - name: API_KEY
    secret: db.schema.api_key_secret

Snowflake mounts each secret as one or more files under /secrets/<name>/. The application reads secret values from these files. File-based delivery lets Snowflake rotate a secret while the container runs; the file content updates in place.

The files written depend on the secret type:

Symmetric key and cloud provider secret types aren’t supported.

OAuth2 secrets require an external access integration: the secret must be listed in the integration’s ALLOWED_AUTHENTICATION_SECRETS, and the integration must be attached to the app through EXTERNAL_ACCESS_INTEGRATIONS on CREATE APPLICATION SERVICE. Password and generic string secrets don’t require an external access integration.

Read a generic string secret:

import { readFileSync } from "node:fs";
const apiKey = readFileSync("/secrets/API_KEY/secret_string", "utf8").trim();

with open("/secrets/API_KEY/secret_string") as f:
    api_key = f.read().strip()

Read a password secret:

import { readFileSync } from "node:fs";
const username = readFileSync("/secrets/DB_CREDENTIALS/username", "utf8").trim();
const password = readFileSync("/secrets/DB_CREDENTIALS/password", "utf8").trim();

with open("/secrets/DB_CREDENTIALS/username") as f:
    username = f.read().strip()
with open("/secrets/DB_CREDENTIALS/password") as f:
    password = f.read().strip()

Read an OAuth2 access token:

import { readFileSync } from "node:fs";
const oauthToken = readFileSync("/secrets/OAUTH_TOKEN/access_token", "utf8").trim();

with open("/secrets/OAUTH_TOKEN/access_token") as f:
    oauth_token = f.read().strip()

Validation during the build phase¶

When your project includes app.yml and you run snow app deploy, Snowflake loads and validates the manifest from uploaded source during the build phase. If the file is missing, Snowflake can still auto-detect build and run behavior from your project layout.

If app.yml is present but invalid, the build fails before a new package version is published. Common causes include:

• YAML syntax errors.
• Invalid profile.icon values (path traversal, absolute paths, or unsupported image formats).

The error message includes parser details, for example:

Application service manifest (app.yaml) cannot be parsed. '<details>'.

Example¶

install:
  commands:
    - [npm, ci]
build:
  commands:
    - [npm, run, build]
run:
  command: [node, dist/server.js]
artifacts:
  - src: "dist/**"
    dest: "."
profile:
  icon: assets/logo.png
  label: Customer Portal
  description: Customer portal web UI.
environment_variables:
  - name: LOG_LEVEL
    value: "INFO"
secrets:
  - name: API_KEY
    secret: db.schema.api_key_secret