Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Installation

Sutra ships as two things, released together and versioned together:

What it isHow you get it
sutrathe CLI that scaffolds, packages, lints, deploys and inspectsone-line install, below
sutra-enginethe runtime that executes your processesa container image, docker pull

Neither needs a Rust toolchain. You only need one to build from source, which is the last section on this page.

Install the CLI

curl -fsSL https://raw.githubusercontent.com/startr-trade/sutra/main/scripts/install.sh | sh

On Windows (PowerShell):

irm https://raw.githubusercontent.com/startr-trade/sutra/main/scripts/install.ps1 | iex

The installer downloads the release build for your platform, verifies its SHA-256 against the release’s own SHA256SUMS, and installs it — into /usr/local/bin when that is writable, otherwise ~/.local/bin. It edits no shell profile and starts no daemon.

Useful knobs:

# Pin a version instead of taking the newest release
curl -fsSL …/install.sh | sh -s -- --version v0.8.3

# Install somewhere specific
curl -fsSL …/install.sh | SUTRA_INSTALL_DIR=~/bin sh

# Lift the API rate limit when retrying (60 requests/hour anonymous -> 5000 with a token)
GH_TOKEN=$(gh auth token) curl -fsSL …/install.sh | sh

If the install fails

raw.githubusercontent.com rate-limits and answers 429 Too Many Requests under load; so does the GitHub API, at 60 requests an hour per IP without a token. Three ways around it, in the order worth trying:

# 1. the SAME installer, served from the release instead of the raw CDN (different host, and
#    the script is versioned with the binaries it installs)
curl -fsSL https://github.com/startr-trade/sutra/releases/download/v0.8.3/install.sh \
  | sh -s -- --version v0.8.3

# 2. a token, which moves the API to 5000 requests an hour
GH_TOKEN=$(gh auth token) curl -fsSL …/install.sh | sh

# 3. no installer at all — the assets are plain files
#    (swap in your target: aarch64-unknown-linux-musl, aarch64-apple-darwin, x86_64-apple-darwin)
gh release download v0.8.3 -R startr-trade/sutra \
  -p 'sutra-*-x86_64-unknown-linux-musl.tar.gz' -p SHA256SUMS
sha256sum --ignore-missing -c SHA256SUMS
tar xzf sutra-*-x86_64-unknown-linux-musl.tar.gz --strip-components=1 -C ~/.local/bin

The installer retries transient failures and times out rather than hanging, and it resolves the release from three different endpoints (/releases/latest, the release list, then git tags), because each of them has been observed failing while a release was perfectly installable. When all three come up empty it tells you to pin --version, which is the one path that needs no lookup at all.

Prefer to see what you are running before you run it? Download install.sh, read it — it is about a hundred lines of POSIX shell — then execute it. Or skip the script entirely and grab the archive yourself from the releases page.

Verify the install:

sutra --version

It prints the version and the build it came from, for example sutra 0.8.3 (1a2b3c4, built 2026-11-15): the release commit and that commit’s date.

Published targets

linux x86_64, linux aarch64, macOS arm64, macOS x86_64, windows x86_64.

x86_64arm64
Linux✅ static musl✅ static musl
macOS✅ built natively✅ built natively
Windows✅ MSVC—

The Linux builds are static musl, so there is no glibc version to match — they run on an old distribution and a new one alike. The macOS builds are compiled on Apple hardware of each architecture rather than cross-compiled.

This table is the CLI. The engine is a container, and its image is Linux only (linux/amd64 + linux/arm64) — which is not a limitation in practice: on macOS or Windows you author, lint, package and deploy with the native CLI, and the engine runs as a Linux container through Docker Desktop, exactly as it does in production. There is no native macOS or Windows engine build, and none is planned.

On Apple silicon that container runs natively, which is why the absence costs so little. The image is a multi-arch manifest, so docker pull resolves to linux/arm64 on its own, and that arm64 build is compiled on a native arm64 runner rather than cross-built or emulated. Docker on macOS is always a Linux VM, and on Apple silicon that VM is arm64 — so you get native-speed execution of the same artifact production runs. (The reverse would be emulated: an linux/amd64 image on Apple silicon goes through Rosetta 2 or QEMU, which is slower and occasionally fails outright. Nothing here asks you to do that.)

On an Apple-silicon Mac running the installer under Rosetta 2, uname -m answers x86_64, so you get the Intel build — it runs, translated. Pass --version and fetch the aarch64-apple-darwin archive by hand if you want the native one.

The macOS binaries are unsigned and un-notarized. That matters only for how you obtained them: a file downloaded by a browser carries com.apple.quarantine, and Gatekeeper refuses it until you clear the attribute —

xattr -d com.apple.quarantine ./sutra

— while an archive fetched by the installer (or any curl) has no such attribute and simply runs. The installer does not strip it for you: quietly removing a security attribute is not an installer’s business.

Get the engine image

docker pull ghcr.io/startr-trade/sutra:0.8.3

One generic image runs every application: behavior comes entirely from the deployment packages you mount or deploy into it. The quickstart starts it for you with Docker Compose, so you can skip this step if you are heading straight there.

Staying current

sutra self-update --check      # is there a newer release? (changes nothing)
sutra self-update              # replace this binary with the newest release
sutra self-update --runtime    # …and pull the matching engine image
sutra self-update --runtime-only   # only the engine image

Updates are never automatic — nothing runs on a timer or as a side effect of another command. Every download is checksum-verified against the release’s SHA256SUMS before it is installed, and the binary is replaced by an atomic rename, so an interrupted update cannot leave a half-written executable on your PATH. --version <tag> pins or rolls back; without it, self-update only ever moves to a newer release. Release candidates count as older than their release, and compare by number (rc.10 is newer than rc.9).

Keeping the CLI and the engine on the same release is worth doing deliberately: they are built, tested and published from one tag, which is what --runtime is for.

Build from source

You need a stable Rust toolchain. Docker is needed only for the container test tier.

git clone https://github.com/startr-trade/sutra.git
cd sutra

make test                                        # the no-docker suite
cargo install --path rust/crates/sutra-cli       # install the CLI you just built
docker build -t sutra-engine:dev -f rust/Dockerfile rust/   # the engine image

Next

Quickstart — a running engine and your first message flowing through it, in about five minutes.