What is Stackie?

Stackie is a sandbox-first cross-platform runtime for development services. Declare your development stack in a stackie-stack.yml file and spin it up with a single command — with full sandbox isolation on every platform.

stackie up

Stackie installs two binaries:

• stackie — the CLI you interact with
• stackied — the background daemon that manages sandboxes and Docker API compatibility

Both are installed to ~/.stackie/bin/. No sudo or admin rights required.

Key Concepts

• Block — a single service or tool (e.g., stackie.postgres, stackie.redis). Each block has a sandbox profile, health checks, and cross-platform install logic.
• Stack — a collection of blocks declared in a stackie-stack.yml file.
• Sandbox — an OS-level isolation boundary. Stackie uses Seatbelt on macOS, Linux namespaces on Linux, and AppContainer on Windows.

Platform Support

Installation

All binaries install to ~/.stackie/bin/. No sudo or admin rights required.

macOS (ARM64 and x86_64)

Supports Apple Silicon (M1-M4) and Intel Macs running macOS 11 (Big Sur) or later.

curl -fsSL https://stackie.dev/install.sh | sh

After install, you may need to run source ~/.zshrc (or source ~/.bashrc) to use stackie in your current terminal session.

Linux (x86_64 and ARM64)

Statically linked musl binary — works on Ubuntu 20.04+, Debian, Fedora, Arch, and others. No glibc dependency.

curl -fsSL https://stackie.dev/install.sh | sh

Ubuntu 23.10+ note: Ubuntu 23.10+ restricts unprivileged user namespaces. You may need to configure AppArmor. See the Linux setup guide.

Windows (x86_64)

Requires Windows 10 or later (64-bit). PowerShell 5.1+ (pre-installed).

powershell -c "irm stackie.dev/install.ps1 | iex"

Windows Defender note: SmartScreen may prompt on first run. Click “More info” then “Run anyway”. See the Windows setup guide.

Inspecting the Script Before Running

macOS / Linux:

curl -fsSL https://stackie.dev/install.sh -o install.sh
less install.sh    # review
sh install.sh

Windows (PowerShell):

irm stackie.dev/install.ps1 -OutFile install.ps1
notepad install.ps1    # review
.\install.ps1

Verify Installation

stackie --version

Updating

Stackie keeps itself up to date. The daemon checks for new versions in the background and surfaces an Update Now entry in the system tray menu when one is available — clicking it applies the update with zero downtime. The same flow is also available from the CLI via stackie update.

See the Self-Update System docs for the full picture: how updates are downloaded and verified, the rollback mechanism, and the available CLI flags.

Uninstalling

macOS / Linux:

# Remove binaries and data
rm -rf ~/.stackie

# Remove PATH entry from your shell rc file
# Edit ~/.zshrc or ~/.bashrc and delete the
# # stackie start ... # stackie end block

Windows (PowerShell):

# Remove binaries and data
Remove-Item -Recurse -Force "$env:USERPROFILE\.stackie"

# Remove PATH entry
$path = [Environment]::GetEnvironmentVariable('PATH','User')
$newPath = ($path -split ';' | Where-Object { $_ -notlike "*\.stackie\bin*" }) -join ';'
[Environment]::SetEnvironmentVariable('PATH', $newPath, 'User')

Managed Mode

Stacks can opt into managed mode by adding mode: managed (or mode: secrets-only) to their stack YAML file. Managed mode activates automatic port allocation and secret injection before any block starts.

Stack Modes

Serves and Consumes

In managed and secrets-only modes, blocks declare their exposed ports using serves: and express cross-block dependencies using consumes:.

my-stack:
  mode: managed
  blocks:
    stackie.postgres:
      name: "db"
      serves:
        PORT: { port: 5432, type: db }

    my-api:
      path: "./backend"
      consumes:
        db: db         # logical alias -> block name
      vars:
        DATABASE_URL: "postgresql://localhost:${consumes.db.PORT}/myapp"

The port allocator assigns stable numbers from a per-stack lock file so that ${consumes.db.PORT} resolves consistently across stackie up invocations.

Secrets

Secrets are stored in OpenBao (an open-source HashiCorp Vault fork) that Stackie manages as a sidecar. Values are written at startup from a {stack}.secrets.yml sidecar file and injected into block environments via ${secrets.KEY} references.

# stacks/my-stack.secrets.yml
secrets:
  DATABASE_PASSWORD: "dev-only-placeholder"
  API_KEY: "dev-only-placeholder"

# stacks/my-stack.yml
my-stack:
  mode: managed
  blocks:
    my-api:
      vars:
        DB_PASS: "${secrets.DATABASE_PASSWORD}"

To manage secrets at runtime:

stackie secrets list my-stack
stackie secrets set  my-stack MY_KEY my-value
stackie secrets get  my-stack MY_KEY
stackie secrets delete my-stack MY_KEY

The secrets panel in the Stackie dashboard provides the same operations via a web UI. Secret values are always masked and revealed only on demand.