Block YAML Format

How to combine with default/stack permissions ("merge" or "replace") Default: "merge"

List of filesystem paths with permission modes

Enable Windows sibling-process IPC compatibility for this block.

This is a Windows-only sandbox relaxation for native service families that create child processes which must signal each other through creator-owned kernel objects such as named pipes. It keeps the user's SID enabled in the Lockbox restricted token for this block's process family. Use sparingly and only for blocks that require this behavior.

URL for x86_64/amd64 architecture

URL for aarch64/arm64 architecture

Short alias accepted by version-aware block consumers (e.g., "21", "3.12").

Full version string used in download URLs, or platform-conditional version map.

Plain strings work as before. Use a platform map when a version is unavailable on a specific OS (e.g., Erlang OTP 28 has no macOS Intel builds):

- alias: "28"
version:
  linux: "28.0.0"
  macos: "27.2.4"
  windows: "28.0.0"

Filters the consumed port by type (e.g., "db", "web"). When set, only ports matching this type are considered. When omitted, any port from the matched block is accepted.

Explicitly names the block that provides this port, bypassing automatic resolution. Also set automatically when the string shorthand form is used (e.g., db: neon sets block_override to "neon").

If both block_override and port_type are set, block_override selects the block and port_type filters which port within it is used.

Handler type to run against the matched content.

Binary path for matched run actions.

Like top-level run hooks, this supports lifecycle interpolation and can reference ${vars.MATCH_PATH} to receive the matched local file.

Command-line arguments for matched run actions.

Optional working directory for matched run actions.

Render POSIX shell echo environment substitutions before this action runs.

Source-image entrypoint files sometimes use constructs such as ` echo "$POSTGRES_USER" inside data files that are later consumed by another binary. Enabling this option materializes a matched-file copy with those shell echo substitutions resolved through the hook environment, then points ${vars.MATCH_PATH}` at the rendered copy for this action.

Variable overrides applied while this action runs.

These values are merged into the handler context for the action only. They are useful when one glob expansion must feed the same primitive through different connection identities or handler settings.

Continue executing actions or matches if this action fails.

Timeout for this action in seconds.

Handler type: "sql", "shell", "write_file", "for_each_match", or "run"

Source type: "git", "web", or "local" Optional for write_file handler which uses path/content instead

Source configuration Optional for write_file handler which uses path/content instead

File patterns to process (glob) Optional for write_file handler which uses path/content instead

Target path for write_file handler Supports variable interpolation (${paths.}, ${vars.}, ${ports.*})

Inline content for write_file, sql, or shell handlers.

For sql and shell, inline content is used when source_config is omitted and files is empty.

Supports variable interpolation (${paths.}, ${vars.}, ${ports.*})

Actions to run for every file matched by a for_each_match hook.

Sources whose relative matches should shadow primary for_each_match files.

When a fetched primary file has the same relative path as any file from a skip_if_matches source, the primary file is skipped. This keeps overlay semantics generic: block YAML can model mounted files shadowing packaged files without teaching Stackie about a particular product or file type.

Interpolated paths that skip the whole hook when any one already exists.

This models source-image entrypoint guards such as "run init files only before a data directory is initialized" without making the hook executor aware of a specific product, file format, or service.

Interpolated paths that skip the whole hook when any one is missing.

Blocks can pair this with declarative init operations that write marker files when fresh state is created, then run connection-dependent hooks only for that startup.

Binary path for the run handler.

Values support the same interpolation as other hook fields, including ${install.path}, ${paths.}, ${vars.}, ${env.}, and ${ports.}.

Command-line arguments for the run handler.

Each argument is interpolated independently before the existing Stackie declarative run operation executes the process.

Optional working directory for the run handler.

Variable overrides applied while this hook runs.

Overrides are merged into the handler context before source paths, inline content, and handler connection settings are interpolated. Nested then actions can add their own overrides on top.

Whether for_each_match should fail when no files match.

Execution order (lower = earlier)

Continue executing hooks if this one fails

PostgreSQL SQLSTATE codes that should be treated as successful no-ops.

This keeps idempotent SQL hooks precise: the hook can tolerate one known database state, such as a duplicate catalog object, while still failing on all other SQL errors.

SQL query that skips this SQL hook when it returns at least one row.

The query uses the same connection string and interpolation context as the hook's SQL content. This lets block definitions avoid expected database errors, such as duplicate catalog objects, instead of executing failing SQL and relying on ignored SQLSTATE codes that still pollute service logs.

Timeout for this hook in seconds

Run this hook only once per block version per project.

When true, the hook is skipped on subsequent stackie up invocations if a matching (block_name, block_version, project_name) record exists in block_init_runs. If no database pool is available, or the block version is "latest", the hook always runs.

Only meaningful on after_healthy hooks. Ignored on all other hook points.

Source to inspect for shadowing matches.

File patterns to match in the shadowing source.

Whether this Docker-compatible image is supplied by Stackie's bundled runtime instead of an installed package source.

Built-in images are still declared by block YAML, so mocker continues to resolve Docker image names through the same catalog path as installable packages. Pull requests for built-in blocks report an already-present image and do not mutate package state.

Docker-facing version reported for a built-in image.

Use this when a compatibility block intentionally emulates a known image tag while the Stackie block name remains honest about the implementation.

Default regex for extracting version from Docker image tags. Applied to all images unless overridden. Example: ^(\d+(?:\.\d+)*) extracts "15.2" from "postgres:15.2-alpine"

Docker image name aliases that map to this block. Supports both simple strings and extended objects.

Additional Docker/Compose hostnames that should resolve to this block.

Some Docker-compatible gateway configs route to stable upstream hostnames that are not the Compose service name or generated container name. Stackie exports these aliases into the Compose endpoint catalog so thin adapters such as Donkey can route through the same generic service resolver.

Container path where user source code is mounted.

When non-None, this block is treated as a user-code runtime block. The user-code detector uses this path to validate bind-mount targets (Pattern A) and to set the default working directory for translated blocks.

Example: /app for Node.js, /workspace for Go.

Default entrypoint command for runtime blocks.

When a container or pod is started with this block's image but no explicit command, this default is used by the user-code detector translation.

Example: ["node", "index.js"] for Node.js, ["python", "main.py"] for Python.

Package manager commands that mocker is allowed to execute during Dockerfile RUN interception (Tier-1 whitelist).

Only argv[0] is matched. Commands not in this list produce a Tier-2 diagnostic pointing users at tools:.

Example: ["npm", "yarn", "pnpm", "npx"] for Node.js.

URL(s) for Linux

URL(s) for macOS

URL(s) for Windows

Port number

Port type classification (optional, defaults to None for backward compatibility)

Whether this served port should be shown as a stack-level external link.

Optional display label for an exposed external link.

URL scheme for exposed external links.

Absolute filesystem path

Permission mode: combination of r/w/x (e.g., "rwx", "rx", "r")

Hash for AMD64/x86_64 architecture

Hash for ARM64/aarch64 architecture

Hashes for macOS (by architecture)

Hashes for Linux (by architecture)

Hashes for Windows (by architecture)

Package name in the source system Example: "postgresql" for brew, "@nestjs/core" for npm

Optional provider-specific version or version constraint.

An empty value inherits the canonical version mapped by the block's latest version alias. Set this only when the provider requires a different selector, such as a package-manager channel or constraint. Examples: "15", "^2.1.0", "latest".

Optional provider spelling applied to the canonical block version.

The template must contain exactly one {version} placeholder and may add provider-required punctuation around it. For example, a Go module whose tags are prefixed with v uses "v{version}", while its web URL can continue to interpolate the unprefixed canonical version. This is not a URL template and cannot add path separators.

Whether this source should be cached on the Cache CDN

Defaults to true. When enabled, stackie will check the Cache CDN first before falling back to the direct source URL. This provides faster, more reliable downloads through a nearby CDN.

Set to false to opt out of CDN caching for sources that should always be fetched directly from upstream (e.g., rapidly changing packages).

Package manager sources (brew, scoop, pip, etc.) ignore this field as they are inherently non-cacheable.

Download URL for web sources (optional, used by web source type)

Supports three formats:

• Simple string: Same URL for all platforms
• Platform map: Different URLs per OS - Platform+Arch map: Different URLs per OS and architecture

Examples F0

Homebrew tap (optional, used by brew source type) Example: "mongodb/brew", "hashicorp/tap"

Ecosystem type for supercache sources

Required when using supercache source type to specify which ecosystem the package belongs to (go, node, python, java, etc.)

Examples F0

Override whether this package is platform-specific

When set, overrides the ecosystem's default platform-specificity. Use this for Node packages with native dependencies that require platform-specific builds.

Examples F0

Source URL for fallback compilation (optional)

For Go packages: The Go module path used for go install when falling back from cached binaries to source compilation. Example: "github.com/supabase/auth", "github.com/traefik/traefik/v3"

For other ecosystems: May be used for source compilation fallback.

Commands to run after installation completes

These commands run in the installation directory after the source has been downloaded/installed. Useful for:

• Running npm install for Node.js projects - Running npm run build to compile TypeScript - Running pip install -r requirements.txt for Python projects - Any post-installation setup required before the package can be used

Examples F0

GitHub repository for github-releases source (owner/repo format)

Used by the github-releases source type to construct download URLs. Format: "owner/repo" (e.g., "PostgREST/postgrest")

Examples F0

Archive filename pattern for github-releases source

Supports placeholders:

• {version} - version tag (e.g., "v12.2.8")
• {platform} - platform name (e.g., "linux", "macos", "windows")
• {arch} - archive architecture name (typically "amd64" or "arm64")

Examples F0

Archive layout for github-releases source.

universal means the archive pattern is the same across platforms. platform_arch means the archive pattern contains platform and/or architecture placeholders and requires matching platform hash metadata.

Platform placeholder mappings for github-releases archive filenames.

Keys are Stackie platform identifiers (macos, linux, windows); values are the strings used by the release asset naming convention. Omit this field to use the github-releases source defaults.

Architecture placeholder mappings for github-releases archive filenames.

Keys are Rust-style architecture identifiers (x86_64, aarch64) plus any block-facing aliases (amd64, arm64) that the installer may use; values are the strings used in the release asset names. Omit this field to use the github-releases source defaults.

SHA256 hash verification for downloaded archives

Supports two formats:

• Simple string: Single hash for all platforms (when URL is same for all) - Platform/arch map: Different hashes for different platform/arch combinations

Required for github-releases source. Optional but recommended for web source.

Examples F0

Human-readable license name (e.g., "MIT License", "GPL v2 with CE")

URL to the full license text

Publisher or organisation that holds the license (e.g., "Adoptium", "Microsoft")