Install & run.

ADocker & Podman

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

shellpersistent 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. Without it, only DNS, HTTP, TLS, and NTP measurements will run.

Inside a container, starla automatically writes state to /state and reads config from /config. No extra flags needed.

With a config file

shellmount config
# grab the example, edit, and mount it
curl -LO https://github.com/ananthb/starla/releases/latest/download/config.toml.example
cp config.toml.example config.toml

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

Stateless / Kubernetes

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

shellkey-from-env
# generate a key locally
ssh-keygen -t ed25519 -f starla-key -N ""

# run with key in env (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.

Inspect

shelllogs & pubkey
docker logs -f starla
docker exec starla cat /state/probe_key.pub

BHome Assistant

This repository doubles as a Home Assistant add-on repository. The add-on wraps the ghcr.io container image — nothing is compiled on your device.

1. Open Settings → Add-ons → Add-on Store → ⋮ → Repositories and add https://github.com/ananthb/starla.
2. Install and start the Starla add-on.
3. Copy the probe public key from the add-on log and register it at atlas.ripe.net/apply/swprobe.

The add-on runs with host networking and CAP_NET_RAW, keeps the probe key across updates and restarts, and exposes log level, interface traffic reports, and Prometheus metrics as configuration options.

CDebian · Ubuntu

The .deb package configures the apt repository for future updates automatically.

shellapt
curl -LO https://github.com/ananthb/starla/releases/latest/download/starla_amd64.deb
sudo dpkg -i starla_*.deb
sudo apt update

# arm64: download starla_arm64.deb instead
sudo systemctl enable --now starla

Future updates arrive via sudo apt upgrade starla.

DFedora · RHEL

The .rpm package configures the dnf repository for future updates automatically.

shelldnf
curl -LO https://github.com/ananthb/starla/releases/latest/download/starla.x86_64.rpm
sudo dnf install ./starla*.rpm

# aarch64: download starla.aarch64.rpm instead
sudo systemctl enable --now starla

Future updates arrive via sudo dnf upgrade starla.

ENixOS

Add the starla flake to your NixOS configuration:

nixflake.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 the whole setup. The module handles the systemd service with DynamicUser=true, CAP_NET_RAW, filesystem hardening, and state/config/runtime directories.

Configuration options

Example with options

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

Secret-managed SSH key

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

nixagenix · sops-nix
# 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

shellstate path
# /var/lib/starla/ is managed by systemd
sudo cat /var/lib/starla/probe_key.pub

FRelease tarball

Each tarball contains the binary, a systemd service file, and an example config.

shellfetch
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

shellsystemd
cd starla

sudo install -m 755 starla /usr/bin/starla

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

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

Run directly

shellcaps · root
# needs CAP_NET_RAW for ping/trace
sudo setcap cap_net_raw=eip ./starla/starla
./starla/starla

# or run as root
sudo ./starla/starla

Probe key location

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

GmacOS

Homebrew

shellbrew
brew install ananthb/starla/starla
brew services start starla

# optional GUI tray applet
brew install --cask ananthb/starla/starla-tray

DMG download

Download the .dmg from GitHub Releases. Drag Starla Tray.app to Applications, then double-click Install CLI.command to symlink the starla binary into /usr/local/bin.

The DMG also includes an example config and a launchd plist for running the probe as a background service.

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

nix-darwin

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

# in your darwin modules:
starla.darwinModules.default
{ services.starla.enable = true; }

Home Manager (macOS & Linux)

The Home Manager module runs starla as a user-level service with declarative config. On macOS it uses launchd agents and copies the tray app to ~/Applications; on Linux it uses systemd user services.

nixhome-manager
inputs.starla.url = "github:ananthb/starla";

{
  imports = [ starla.homeManagerModules.default ];

  services.starla = {
    enable = true;
    logLevel = "info";
    tray.enable = true;  # install + auto-start the tray app
  };
}

The module generates ~/.config/starla/config.toml from your declarative options. On macOS, enabling the tray copies Starla Tray.app to ~/Applications and creates launchd agents for both the probe and the tray. On Linux it creates systemd user services and a desktop autostart entry.

HWindows

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

shellafter install
# open a new terminal, then:
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).

IAfter install

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 (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 running measurements.

JConfig file

See config.toml.example for all options. The config file is optional — every setting has a sensible default.

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)

Next: verify your downloads →

KLanguage

The tray app follows your desktop language, falling back to English for anything not translated yet. Override it with STARLA_LANG — handy for checking a translation without changing system settings:

shelllanguage override
STARLA_LANG=es starla-tray

Probe logs stay in English so they remain greppable and easy to paste into an issue. Translations are made on Weblate: adding a language takes no code change and no pull request.