Stack YAML Format

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.

How often to perform health checks (seconds) Default: 30 seconds

How long to wait for response (seconds) Default: 5 seconds

Number of consecutive failures before marking unhealthy Default: 3 retries

Grace period before starting health checks (seconds) Allows time for sandbox to initialize Default: 0 seconds

Delay before the first health probe is executed (seconds).

This is distinct from start_period: start_period is Docker's retry accounting grace window, while initial_delay prevents noisy or disruptive probes from being sent before a process can accept them.

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.

Local source directory for first-party (user-owned) blocks. When set, this block is treated as a locally-owned service whose source code lives at this path, relative to the directory where stackie up is run.

Must be a relative path pointing to a subdirectory of the working directory. Absolute paths and .. traversal are not allowed.

When omitted, the block is resolved as a third-party ingredient from the registry.

Dependencies that must start before this block.

Defaults to empty list if not specified.

Logical port consumption declarations for managed-mode port resolution.

Accepts two YAML forms:

List form (preferred) — each entry is a block instance name. The name is used directly as the interpolation key: F0

Map form — each key is a logical alias for the consumed block: F1

Only meaningful when the parent CompositeStack::mode is StackMode::Managed.

Custom display name for this block instance If not specified, defaults to the block type name (e.g., "postgres" from "stackie.postgres") This is similar to docker's --name flag for containers.

Example F0

Required on gateway.* blocks. Identifies which compiled Gateways provider receives requests for this block.

Accepted values: aws, gcp, azure, cloudflare. The generated Gateway reference page expands the provider table from Gateways runtime metadata, including display names, default ports, and backing-service behavior.

Example YAML

gateway.cloudflare:
  provider: cloudflare
  serves:
    API: { port: 4569, type: api }

Override version

Override environment variables

Named port configurations served by this block (accessed as ${serves.NAME}).

Declares the ports that this block exposes to the stack. In managed mode, the port allocator reads these entries to assign stable port numbers from the static-DHCP pool. Port numbers declared here are whitelisted in the sandbox policy.

Accepts ports as a serde alias for backward compatibility: existing YAML files that use ports: continue to parse without modification.

Example YAML

stackie.postgres:
  serves:           # or
  legacy:
    ports:
      PORT: { port: 5432, type: db }

Override string variables (accessed as ${vars.NAME}) These override the default vars defined in the block

Override filesystem paths (accessed as ${paths.NAME}).

Maps a logical path name to the sandbox-side mount path. The physical host directory is derived as: ~/.stackie/storage/volumes/{project}/{path_name}/{sandbox_path_stripped}/

The directory is created automatically before the process starts and the sandbox policy grants read-write access to it.

Defines commands to run at specific points in the block's lifecycle (e.g., after start, before stop). Hooks are keyed by lifecycle event name.

Declarative setup operations (e.g., ensure_dir, copy, write_file) that run after the block's built-in init sequence. Lets stacks provide custom configuration not included in the block definition.

Example YAML

stackie.tomcat:
  init:
    - write_file:
      path: "${paths.base}/conf/server.xml"
      content: |
        <?xml version="1.0" encoding="UTF-8"?> <Server port="-1" shutdown="SHUTDOWN"> ... </Server>
    - ensure_dir: "${paths.base}/logs"

Required for first-party blocks (those with path: set). Specifies the process to run.

Accepts a string (shell-interpreted) or an array of strings (direct exec):

command: "npm run dev"          # shell-parsed
command: ["npm", "run", "dev"]  # direct exec (preferred)

Declares the tools (and versions) that must be available before this block's command runs. The tool manager provisions each tool automatically if not already installed.

Each entry is a single-key map of tool name to version:

tools:
  - node: "20"
  - python: "3.11"

Health check configuration for this block.

Provides (for first-party blocks) or overrides (for third-party blocks) the health check used by the daemon to monitor block availability.

Uses bridge's own HealthCheck type, which supports HTTP, TCP, command, and process-based checks.

Display emoji for topology view.

Overrides the block's default emoji in the dashboard topology node. For first-party blocks, this is the only way to set a topology icon.

Example

emoji: "🚀" — shown in the topology node for this block instance.

Controls sandbox isolation for first-party blocks. Defaults to true (sandbox enabled) when omitted. Only applies to first-party blocks; third-party blocks are always sandboxed.

Set to false for development workflows that need unrestricted filesystem access. A warning is shown whenever sandbox isolation is disabled.

Lists sibling blocks whose installed native libraries should be visible to this block at runtime. This is useful when a stack replaces a generic dependency with a specialized block.

Example YAML

stackie.postgrest:
  depends_on:
    - stackie.supabase-postgres
    links:
      - stackie.supabase-postgres

Maps serverless function names to locally-running blocks on gateway.* blocks. When present, the gateway routes invocations to the specified block instead of a container, enabling full IDE debugger attachment without Docker image builds.

Example YAML

gateway.aws:
  provider: aws
  bindings:
    my-lambda-function: my-lambda-block
    another-function: another-block

Variable overrides applied to ALL blocks in the substack (global scope).

These values are merged with each block's own vars, with the override values taking precedence.

Port overrides for blocks within the substack. The outer key is the block name (as declared in the substack), the inner key is the port name. The referenced block must exist in the substack.

Overrides the storage root for all blocks resolved from this substack. See storage_root on the top-level stack for full semantics.