Installation

Softprobe has four installable pieces. You pick the ones you need:

Piece	Install for…	Ships as
Runtime (softprobe-runtime)	Hosting the control plane yourself	Docker image + static binary
CLI (softprobe)	Scripting capture, running suites, CI	Homebrew, curl-install, npm
Proxy (Envoy + Softprobe WASM)	Intercepting HTTP in your environment	WASM binary + Envoy config
SDK (one per language)	Authoring tests	npm, PyPI, Maven Central, Go modules

A typical laptop-dev setup uses all four via docker compose and a local npm install. A typical CI setup uses the Docker image + the CLI binary + the SDK for the test language.

Runtime

Docker (recommended)

docker run -p 8080:8080 ghcr.io/softprobe/softprobe-runtime:v0.5

The image is ~30 MB (distroless base) and starts in under a second. The only required environment variable is SOFTPROBE_LISTEN_ADDR (defaults to 0.0.0.0:8080).

Variable	Default	Purpose
SOFTPROBE_LISTEN_ADDR	0.0.0.0:8080	HTTP bind address for both control API and OTLP
SOFTPROBE_CAPTURE_CASE_PATH	(unset)	Where to flush captured cases on session close
SOFTPROBE_LOG_LEVEL	info	debug, info, warn, error

Binary (Linux / macOS)

curl -fsSL https://softprobe.dev/install/runtime.sh | sh

Installs /usr/local/bin/softprobe-runtime. Verify:

softprobe-runtime --version
# softprobe-runtime v0.5.0 (commit abcdef, built 2026-04-15)

Source (Go 1.22+)

git clone https://github.com/softprobe/softprobe-runtime
cd softprobe-runtime && go build -o softprobe-runtime .
./softprobe-runtime

Hosted option

If you do not want to operate the runtime yourself, point your CLI and SDKs at https://o.softprobe.ai (see Hosted deployment). It speaks the same HTTP control API and OTLP trace API as the OSS runtime.

CLI

The CLI is the primary interface for humans, CI pipelines, and AI agents. It speaks only HTTP to the runtime — no local state.

Homebrew (macOS / Linux)

brew tap softprobe/tap
brew install softprobe

Curl installer (Linux / macOS)

curl -fsSL https://softprobe.dev/install/cli.sh | sh

Installs /usr/local/bin/softprobe.

Windows (Scoop)

scoop bucket add softprobe https://github.com/softprobe/scoop-bucket
scoop install softprobe

npm (cross-platform, pinned to a release)

npm install --save-dev @softprobe/cli
npx softprobe doctor

The npm package ships a Node wrapper that delegates to the canonical Go binary for your platform.

Verify

softprobe --version
# softprobe 0.5.0

softprobe doctor
# ✓ runtime reachable at http://127.0.0.1:8080
# ✓ schema version matches CLI (spec v1)
# ✓ proxy WASM binary at expected path

If doctor reports red, fix the flagged item before continuing.

Proxy

The proxy is an Envoy binary with the Softprobe WASM filter loaded. You can run it directly or through a service mesh.

Local Docker Compose (easiest)

Copy e2e/docker-compose.yaml and e2e/envoy.yaml from the main repository. They wire a single Envoy with one ingress listener and one egress listener, both pointing at the runtime.

docker compose -f e2e/docker-compose.yaml up --wait

Standalone Envoy

If you already run Envoy, add the Softprobe WASM filter to your HTTP filter chain:

http_filters:
  - name: envoy.filters.http.wasm
    typed_config:
      "@type": type.googleapis.com/envoy.extensions.filters.http.wasm.v3.Wasm
      config:
        name: softprobe
        configuration:
          "@type": type.googleapis.com/google.protobuf.StringValue
          value: |
            {"sp_backend_url":"http://softprobe-runtime:8080"}
        vm_config:
          runtime: envoy.wasm.runtime.v8
          code:
            local: { filename: /etc/envoy/sp_istio_agent.wasm }

Download the WASM binary from the releases page.

Istio

In a mesh, attach the filter to your workload with a WasmPlugin resource. See Kubernetes deployment for the full manifest.

SDKs

Install the SDK for the language your tests are written in. You can install more than one if your services span languages.

TypeScript / JavaScript

npm install --save-dev @softprobe/softprobe-js

import { Softprobe } from '@softprobe/softprobe-js';

const softprobe = new Softprobe({ baseUrl: process.env.SOFTPROBE_RUNTIME_URL });

Reference: TypeScript SDK.

Python

pip install softprobe

from softprobe import Softprobe

softprobe = Softprobe(base_url="http://127.0.0.1:8080")

Reference: Python SDK.

Java (Maven)

<dependency>
  <groupId>dev.softprobe</groupId>
  <artifactId>softprobe-java</artifactId>
  <version>0.5.0</version>
  <scope>test</scope>
</dependency>

Reference: Java SDK.

Go

go get github.com/softprobe/softprobe-go@v0.5.0

import "github.com/softprobe/softprobe-go/softprobe"

Reference: Go SDK.

One-liner: everything for a laptop

curl -fsSL https://softprobe.dev/install/cli.sh | sh
git clone https://github.com/softprobe/softprobe
cd softprobe
docker compose -f e2e/docker-compose.yaml up --wait
softprobe doctor

After that, follow the Quick start.

Version matrix

Component	Current release	Minimum compatible CLI	Minimum compatible SDK
Runtime	v0.5.0	v0.5.0	v0.5.0
CLI	v0.5.0	—	v0.4.0+
Proxy WASM	v0.5.0	v0.5.0	—
Spec	v1	v0.5.0	v0.4.0+

softprobe doctor warns when versions drift out of range.

Uninstall

# Homebrew
brew uninstall softprobe && brew untap softprobe/tap

# curl install
sudo rm /usr/local/bin/softprobe /usr/local/bin/softprobe-runtime

# npm
npm uninstall @softprobe/cli @softprobe/softprobe-js

Case files, if any, remain — they are plain JSON you own.

---

Next: Quick start → or Architecture →