Last updated 2026-05-07

Installation

stax ships as a single Go binary plus a Node.js runner. The CLI works standalone for stacked-diff features; the runner is required if you want to execute workflows locally. Repo-backed secrets use the external sops CLI for file encryption; Stax manages the age identity and orchestration around it.

1. Install the CLI

Homebrew (macOS / Linux)

brew install elloloop/tap/stax

Installs the latest stable release from the elloloop/homebrew-tap formula. Auto-detects darwin/arm64, darwin/amd64, linux/arm64, and linux/amd64. Upgrade with brew upgrade stax.

One-line installer (macOS / Linux)

curl -fsSL https://raw.githubusercontent.com/elloloop/stax/main/install.sh | sh

Downloads the latest stax binary from GitHub Releases and installs to $HOME/.local/bin. Override the install directory with STAX_INSTALL_DIR=/usr/local/bin, pin a specific version with STAX_VERSION=2.4.3, or force a source build with STAX_FROM_SOURCE=1. The installer detects linux/amd64, linux/arm64, darwin/amd64, and darwin/arm64.

GitHub Releases

Prebuilt release assets are available for macOS, Linux, and Windows on the GitHub Releases page. macOS users can also install the signed universal DMG when they want the desktop app in addition to the CLI.

Windows (PowerShell)

iwr -useb https://raw.githubusercontent.com/elloloop/stax/main/install.ps1 | iex

Detects windows/amd64 and windows/arm64. Installs to %LOCALAPPDATA%\stax\bin by default.

From source

git clone https://github.com/elloloop/stax.git
cd stax/platform/cli-go
go build -o stax ./cmd/stax
./stax --version

Requirements: Go 1.26+. The CLI has no runtime dependencies — the binary is statically linked and self-contained.

Verify

stax --version
stax features  # should print "(no features yet)" inside any directory

Optional: install SOPS for repo-backed secrets

brew install sops

# age CLI is optional. Stax can generate age identities itself:
stax secrets keygen
stax secrets pubkey

The sops binary is required for stax secrets edit, verify, export, and runner sync. The standalone age CLI is useful for manual debugging, but Stax can create and read age identities without it.

2. Install the runner

The runner is a Node.js server. It is shipped under platform/runner/ in the same repository as the CLI; you can either clone the repo or install @stax/runner from npm once it is published.

From the repository

git clone https://github.com/elloloop/stax.git
cd stax/platform/runner
npm install
npm run build

Requirements:

• Node.js ≥ 18 (the runner is tested on 22)
• Git (used for sandbox worktrees and to download marketplace actions)
• Docker (optional — only needed for Docker-based actions and services: blocks)

Start the runner

# Foreground (development)
cd platform/runner && npm run dev

# Background, via the CLI (preferred)
stax runner start --workspace /path/to/your/project --port 4800

The runner banner confirms which workspace it is serving:

Local GitHub Actions runner started
  API:       http://localhost:4800/api
  Events:    http://localhost:4800/api/events
  Health:    http://localhost:4800/health
  Workspace: /path/to/your/project

3. Install the web dashboard (optional)

The dashboard is a Next.js application under platform/web/. It connects to the runner over its REST and SSE APIs.

cd platform/web
pnpm install   # or npm install
pnpm dev       # http://localhost:3000

The CLI shortcut stax dashboard launches the dashboard in dev mode and opens it in your default browser.

4. Container images (RunPod / remote dev)

stax also publishes prebuilt container images for remote development. Three flavours, all available at ghcr.io/elloloop/stax:

docker pull ghcr.io/elloloop/stax:base
docker pull ghcr.io/elloloop/stax:inference
docker pull ghcr.io/elloloop/stax:train

See Containerized Dev Pods for the SSH connection helper, environment variables, and tooling reference.

Requirements summary