Skip to content

Quick Start

Jump to bottom
Kris Armstrong edited this page May 19, 2026 · 1 revision

Quick Start

Install

macOS

gh release download --repo krisarmstrong/stem --pattern '*-darwin-arm64.tar.gz'
tar -xzf stem-*-darwin-arm64.tar.gz
STEM_AUTH_USERNAME=admin STEM_AUTH_PASSWORD=admin ./stem web -p 8080

The Stem requires STEM_AUTH_USERNAME and STEM_AUTH_PASSWORD env vars — it fails fast otherwise. TLS is on by default; the binary mints a self-signed certificate at first run. Browser will warn — accept the exception once.

Linux

# Ubuntu / Debian
gh release download --repo krisarmstrong/stem --pattern '*_amd64.deb'
sudo dpkg -i stem_*_amd64.deb

# Fedora / RHEL
gh release download --repo krisarmstrong/stem --pattern '*.x86_64.rpm'
sudo rpm -ivh stem-*.x86_64.rpm

The systemd unit reads credentials from /etc/stem/auth.env. Set them before starting:

sudo install -o root -g root -m 600 /dev/stdin /etc/stem/auth.env <<EOF
STEM_AUTH_USERNAME=admin
STEM_AUTH_PASSWORD=$(openssl rand -base64 24)
EOF
sudo systemctl start stem

First run

  1. Visit https://localhost:8080/ (note: HTTPS even on the default port).
  2. Setup wizard: confirms the admin credentials and asks which role this stem is — Reflector or Test Master.
  3. After setup, the UI lands on either:
    • /reflector if you picked Reflector
    • /tests if you picked Test Master

You can switch role later via the chip in the upper-right of the topbar.

CLI mode

The Stem also has a CLI for headless / scripted use:

stem reflect -i eth0                              # reflector mode on eth0
stem test -t rfc2544_throughput -i eth0           # one-shot benchmark
stem list-tests                                   # all supported test types
stem list-tests --by-module                       # grouped by module
stem help modules

Verify the install

curl -sk https://<host>:8080/__version | jq

uiBuildHash non-empty confirms the React frontend was embedded.

Pre-flight notes

  • Reflector mode requires Linux + CGO build. macOS stem ships without the C dataplane and the Reflector backend will refuse to start with CGO dataplane not available on this platform. Use a Linux stem for the reflecting node.
  • Test Master is fully supported on macOS. RFC 2544 / Y.1564 / Y.1731 traffic generation uses gopacket and works without CGO.
  • Raw sockets: traffic generation needs CAP_NET_RAW. The .deb/.rpm install configures this via systemd AmbientCapabilities. For dev runs, make dev-run sets the cap automatically.

Clone this wiki locally