The seekrit-run launcher

seekrit-run is a compiled, single-file version of seekrit run built for machines. It authenticates with a service token, fetches the bound environment's encrypted secrets, decrypts them locally, layers them under any .env files and the live process environment, and then execs your command. That's all it does — no config files, no caching, no daemon.

SEEKRIT_TOKEN=skt_… seekrit-run -- ./start-server

Degrades gracefully

Fetching seekrit secrets is best-effort. If the token is missing or malformed, or the API can't be reached, seekrit-run logs a warning to stderr and still runs your command with just the .env overlay and the live environment:

seekrit-run: continuing without seekrit-managed secrets: could not reach the seekrit API: …

This means the same launcher works whether or not seekrit is reachable — locally without a token, in CI, or in an offline sandbox — so you can wire it into an image's entrypoint unconditionally. Only genuinely local problems stop it: a usage error, an explicit --env-file that can't be read, or a command that can't be started. The seekrit run subcommand of the Node CLI behaves the same way.

Why use it instead of the CLI?

• Tiny & static. One ~1–2 MB file with no runtime dependencies — no Node, no OpenSSL, no system CA bundle. TLS roots are compiled in, so it runs unchanged in distroless, alpine, and scratch images.
• Same behavior as seekrit run. Identical layer precedence and .env parsing; its decryption is verified bit-for-bit against the browser/CLI crypto.
• Clean process model. On Unix it replaces itself with your command (execvp), so signals and exit codes pass through exactly. On Windows it spawns, waits, and forwards the exit code.

Install

The install script detects your OS and architecture, downloads the matching binary from run.seekrit.dev, verifies its SHA-256 checksum, and drops it on your PATH:

curl -fsSL https://run.seekrit.dev/install.sh | sh

It installs to /usr/local/bin if that's writable, otherwise ~/.local/bin. Override the destination, pin a version, or force a target with environment variables:

# Pin a version and install somewhere specific.
curl -fsSL https://run.seekrit.dev/install.sh \
  | SEEKRIT_RUN_VERSION=0.2.0 SEEKRIT_RUN_INSTALL_DIR="$HOME/bin" sh

Manual download

Prefer to fetch it yourself? Every release is published under a versioned and a latest/ path, each with a .sha256 alongside. On Linux the fully static musl build runs anywhere (glibc, alpine, distroless, scratch):

# Pick your target: {x86_64,aarch64}-{unknown-linux-musl,unknown-linux-gnu,apple-darwin}
curl -fsSL -O https://run.seekrit.dev/latest/seekrit-run-aarch64-apple-darwin.tar.gz
curl -fsSL -O https://run.seekrit.dev/latest/seekrit-run-aarch64-apple-darwin.sha256
shasum -a 256 -c seekrit-run-aarch64-apple-darwin.sha256
tar xzf seekrit-run-aarch64-apple-darwin.tar.gz
install -m 0755 seekrit-run /usr/local/bin/

Windows ships as a .zip (seekrit-run-x86_64-pc-windows-msvc.zip).

Usage

# Token from the environment (or a .env file); resolves org/app/env from it.
SEEKRIT_TOKEN=skt_… seekrit-run -- pnpm start

# Token via flag; everything after -- is the command, verbatim.
seekrit-run --token skt_… -- node --enable-source-maps server.js

# Point at a self-hosted API.
seekrit-run --api-url https://api.your-seekrit.example -- ./app

# Swap one composed group's slice for this run.
seekrit-run --with auth-providers=staging -- ./app

# See where each variable resolved from (stderr; names only, never values).
seekrit-run --explain -- true

Precedence

Highest wins — identical to seekrit run:

process env  >  .env files  >  app-environment secrets  >  group secrets

The live process environment always wins, so a value exported in the shell (or by your orchestrator) overrides anything seekrit resolves.

Options

HTTPS_PROXY / ALL_PROXY are honored for egress-proxied networks.

In a container

Keep Node out of your runtime image entirely — fetch the static binary in a build stage (pin the version and verify the checksum for reproducible images), then copy it into a minimal runtime and make it the entrypoint:

# --- fetch seekrit-run: pinned + checksum-verified --------------------------
FROM alpine:3 AS seekrit
ARG SEEKRIT_RUN_VERSION=0.2.0
ARG TARGET=x86_64-unknown-linux-musl
RUN apk add --no-cache curl && cd /tmp \
 && curl -fsSL -O https://run.seekrit.dev/v${SEEKRIT_RUN_VERSION}/seekrit-run-${TARGET}.tar.gz \
 && curl -fsSL -O https://run.seekrit.dev/v${SEEKRIT_RUN_VERSION}/seekrit-run-${TARGET}.sha256 \
 && sha256sum -c seekrit-run-${TARGET}.sha256 \
 && tar xzf seekrit-run-${TARGET}.tar.gz -C /usr/local/bin

# --- your runtime image: fully static, so distroless/static is enough -------
FROM gcr.io/distroless/static
COPY --from=seekrit /usr/local/bin/seekrit-run /usr/local/bin/seekrit-run
ENTRYPOINT ["seekrit-run", "--"]
CMD ["./start-server"]

docker run --rm \
  -e SEEKRIT_TOKEN="$SEEKRIT_TOKEN" \
  your-image ./start-server

Exit codes

A missing/malformed token, a revoked token or missing key grant, and network failures are not fatal — seekrit-run warns and runs the command without the managed secrets (see Degrades gracefully).

See the CLI reference for the condensed version, and Service tokens for how to mint the token this binary needs.