Install & Run

Docker / Podman

The container image is published to ghcr.io/ananthb/starla for both amd64 and arm64.

# Run with persistent state
docker run -d --name starla \
  -v starla-state:/state \
  --cap-add NET_RAW \
  ghcr.io/ananthb/starla:latest

CAP_NET_RAW is required for ping and traceroute measurements. Without it, only DNS, HTTP, TLS, and NTP measurements will work.

Inside a container, starla automatically stores state in /state and reads config from /config — no extra flags needed.

With a config file

# Download example config
curl -LO https://github.com/ananthb/starla/releases/latest/download/config.toml.example
cp config.toml.example config.toml
# Edit config.toml as needed

docker run -d --name starla \
  -v starla-state:/state \
  -v $(pwd)/config.toml:/config/config.toml:ro \
  --cap-add NET_RAW \
  ghcr.io/ananthb/starla:latest

Podman

podman run -d --name starla \
  -v starla-state:/state \
  --cap-add NET_RAW \
  ghcr.io/ananthb/starla:latest

Stateless / Kubernetes

For environments without persistent storage, pass the SSH private key via the STARLA_SSH_KEY environment variable. No volume mounts needed.

# Generate a key locally
ssh-keygen -t ed25519 -f starla-key -N ""

# Run with key from env var (no persistent state)
docker run -d --name starla \
  -e STARLA_SSH_KEY="$(cat starla-key)" \
  --cap-add NET_RAW \
  ghcr.io/ananthb/starla:latest

Register the public key (starla-key.pub) at atlas.ripe.net/apply/swprobe. The key can be stored as a Kubernetes Secret and mounted as an env var.

View logs and probe key

# Follow logs
docker logs -f starla

# Get the probe public key (when using persistent state)
docker exec starla cat /state/probe_key.pub

Ubuntu / Debian

Download the .deb package from GitHub Releases. The package automatically configures the apt repository for future updates.

# Install (amd64)
curl -LO https://github.com/ananthb/starla/releases/latest/download/starla_0.1.0_amd64.deb
sudo dpkg -i starla_*.deb
sudo apt update

# arm64: download starla_0.1.0_arm64.deb instead

# Enable and start
sudo systemctl enable --now starla

Future updates arrive via sudo apt upgrade starla.

Fedora / RHEL

Download the .rpm package from GitHub Releases. The package automatically configures the dnf repository for future updates.

# Install (x86_64)
curl -LO https://github.com/ananthb/starla/releases/latest/download/starla-0.1.0-1.x86_64.rpm
sudo dnf install ./starla-*.rpm

# aarch64: download starla-0.1.0-1.aarch64.rpm instead

# Enable and start
sudo systemctl enable --now starla

Future updates arrive via sudo dnf upgrade starla.

NixOS

Add the starla flake to your NixOS configuration:

# flake.nix
{
  inputs.starla.url = "github:ananthb/starla";

  outputs = { self, nixpkgs, starla, ... }: {
    nixosConfigurations.myhost = nixpkgs.lib.nixosSystem {
      modules = [
        starla.nixosModules.default
        {
          services.starla.enable = true;
        }
      ];
    };
  };
}

That's it. The module handles everything: systemd service with DynamicUser=true, CAP_NET_RAW, filesystem hardening, state/config/runtime directories.

Configuration options

Option	Default	Description
sshKeyFile	null	Path to SSH private key file (for agenix/sops-nix)
logLevel	"info"	Log verbosity (trace/debug/info/warn/error)
reportInterfaceStats	false	Send network interface traffic statistics
controller.registrationServers	reg03, reg04	RIPE Atlas registration servers
controller.sshTimeout	30	SSH connection timeout (seconds)
controller.keepaliveInterval	60	SSH keepalive interval (seconds)
storage.maxQueueSize	10000	Max results in upload queue
storage.retentionDays	30	Result retention period
metrics.enable	true	Prometheus metrics export
metrics.listenAddr	"127.0.0.1:9695"	Metrics listen address
logging.format	"json"	Log format (json/text)
logging.output	"stdout"	Log destination (stdout/file/syslog)

Example with options

services.starla = {
  enable = true;
  logLevel = "debug";
  metrics.listenAddr = "0.0.0.0:9695";
  storage.retentionDays = 7;
};

Using a secret-managed SSH key

For agenix, sops-nix, or similar secret managers, point sshKeyFile to the decrypted key file. The key is loaded via systemd's LoadCredential.

# With agenix
age.secrets.starla-key.file = ./secrets/starla-key.age;
services.starla = {
  enable = true;
  sshKeyFile = config.age.secrets.starla-key.path;
};

# With sops-nix
sops.secrets.starla-key = { };
services.starla = {
  enable = true;
  sshKeyFile = config.sops.secrets.starla-key.path;
};

Probe key location

# State is at /var/lib/starla/ (managed by systemd)
sudo cat /var/lib/starla/probe_key.pub

Release Tarball

Download the latest release tarball from GitHub Releases. Each tarball contains the binary, systemd service file, and example config.

# Download and extract (amd64)
curl -LO https://github.com/ananthb/starla/releases/latest/download/starla-amd64.tar.gz
tar xzf starla-amd64.tar.gz

# For ARM64:
# curl -LO https://github.com/ananthb/starla/releases/latest/download/starla-arm64.tar.gz

Install as a systemd service

cd starla

# Install binary
sudo install -m 755 starla /usr/bin/starla

# Install config
sudo mkdir -p /etc/starla
sudo install -m 644 config.toml.example /etc/starla/config.toml

# Install and enable service
sudo install -m 644 starla.service /usr/lib/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now starla

Run directly

# Needs CAP_NET_RAW for ping/traceroute
sudo setcap cap_net_raw=eip ./starla/starla
./starla/starla

# Or run as root
sudo ./starla/starla

Probe key location

# As root: /var/lib/starla/probe_key.pub
# As user: ~/.local/state/starla/probe_key.pub
cat ~/.local/state/starla/probe_key.pub

macOS

Homebrew

# Install probe
brew install ananthb/starla/starla

# Start as a service
brew services start starla

# Install tray app (GUI)
brew install --cask ananthb/starla/starla-tray

DMG download

Download the .dmg from GitHub Releases. It contains the starla CLI binary, Starla Tray.app, example config, and launchd plist.

# Download (Apple Silicon)
# https://github.com/ananthb/starla/releases/latest/download/starla-macos-arm64.dmg

# Mount, copy starla to /usr/local/bin, then run
starla

Ping and traceroute work on macOS without root (uses ICMP DGRAM sockets).

nix-darwin

# flake.nix
inputs.starla.url = "github:ananthb/starla";
# In darwin modules:
starla.darwinModules.default
{ services.starla.enable = true; }

Windows

Download the .msi installer from GitHub Releases. It installs the binary to Program Files\Starla and adds it to PATH.

# Download and install
# https://github.com/ananthb/starla/releases/latest/download/starla-windows-amd64.msi

# After install, open a new terminal and run
starla

All measurement types work on Windows. Ping and traceroute use the Windows ICMP Helper API and do not require administrator privileges. UDP and TCP traceroute variants are not yet supported (ICMP traceroute works).

After Installation

1. Start starla — on first run it generates an SSH key and logs the public key
2. Copy the public key from the log output (it's also saved to probe_key.pub in the state directory)
3. Register at atlas.ripe.net/apply/swprobe
4. Starla retries automatically — once approved, it connects and begins measurements

Configuration File

See config.toml.example for all available options. The config file is optional — all settings have sensible defaults.

Config file search order:

1. --config CLI flag
2. $CONFIGURATION_DIRECTORY/config.toml (systemd)
3. $XDG_CONFIG_HOME/starla/config.toml
4. /etc/starla/config.toml (root) or ~/.config/starla/config.toml (user)

See Verifying Downloads to check artifact signatures.