Skip to content

Runner settings

This page lists everything you can set on an SREInsights runner: its environment variables, the identity command, where it keeps its key, and the Docker flags it should run with. For a step-by-step install, see Install a Docker runner and Set up a Lambda runner.

The runner image is public: ghcr.io/bintree-softwares/sreinsights-runner:latest. It is about 50 MB, runs on distroless Node 22 as a non-root user, and has no shell or package manager.

The Runners page gives you a docker run command with your URL and a fresh registration token filled in. This is that command with the hardening flags added:

Terminal window
docker run -d --name sreinsights-runner --restart unless-stopped --stop-timeout 40 \
-e SREINSIGHTS_URL=https://console.sreinsights.com \
-e SREINSIGHTS_REGISTRATION_TOKEN=prt_… \
-v sreinsights-runner:/var/lib/sreinsights-runner \
--read-only --tmpfs /tmp --cap-drop ALL --security-opt no-new-privileges \
ghcr.io/bintree-softwares/sreinsights-runner:latest

On a self-hosted instance, use <your SREInsights URL> for SREINSIGHTS_URL.

The repository’s deploy/compose.runner.yml:

services:
sreinsights-runner:
image: ghcr.io/bintree-softwares/sreinsights-runner:latest
restart: unless-stopped
environment:
SREINSIGHTS_URL: ${SREINSIGHTS_URL:?set SREINSIGHTS_URL to your SREInsights address}
SREINSIGHTS_REGISTRATION_TOKEN: ${SREINSIGHTS_REGISTRATION_TOKEN:-}
SREINSIGHTS_RUNNER_NAME: ${SREINSIGHTS_RUNNER_NAME:-}
SREINSIGHTS_RUNNER_LABELS: ${SREINSIGHTS_RUNNER_LABELS:-}
SREINSIGHTS_RUNNER_CAPACITY: ${SREINSIGHTS_RUNNER_CAPACITY:-4}
volumes:
- sreinsights-runner:/var/lib/sreinsights-runner
# The runner lets running checks finish for up to 30 s after SIGTERM.
stop_grace_period: 40s
read_only: true
# Script checks write their code and output files to /tmp; read_only needs this writable tmpfs.
tmpfs:
- /tmp
cap_drop: [ALL]
security_opt: ["no-new-privileges:true"]
volumes:
sreinsights-runner: {}

Start it with:

Terminal window
export SREINSIGHTS_URL=https://console.sreinsights.com
export SREINSIGHTS_REGISTRATION_TOKEN=prt_… # from the Runners page; needed on first start only
docker compose -f compose.runner.yml up -d

Run two or more runners, on different hosts, in the same runner group for redundancy.

Variable Default Secret What it does
SREINSIGHTS_URL None (required) No Where the runner reaches SREInsights, for example https://console.sreinsights.com. A plain http:// address other than localhost, 127.0.0.1 or ::1 works, but the runner logs a warning
SREINSIGHTS_REGISTRATION_TOKEN Not set Yes A prt_… token from the Runners page. Needed once, on first start. After that the runner signs in with the key in its state directory
SREINSIGHTS_RUNNER_NAME The host name No The name shown on the Runners page, 1 to 100 characters
SREINSIGHTS_RUNNER_LABELS None No Comma-separated custom labels, for example elastic-prod,eu. Lower-cased; each starts with a letter or digit and has up to 63 lower-case letters, digits, ., _ or -. At most 20
SREINSIGHTS_RUNNER_STATE_DIR /var/lib/sreinsights-runner No Where the runner keeps its private keys. Mount a persistent volume here
SREINSIGHTS_RUNNER_CAPACITY 4 No How many runs execute at the same time, from 1 to 50
SREINSIGHTS_RUNNER_HOSTED false No Hosted mode. See Hosted mode
SREINSIGHTS_SCRIPT_ENV_PASSTHROUGH None No Comma-separated names of more variables that runtime: local scripts inherit. See What scripts inherit
SREINSIGHTS_SECRET_<CONNECTION>_<FIELD> None Yes Connection secrets kept on the runner instead of in SREInsights. See Secrets kept on the runner
SREINSIGHTS_JOB_TYPES_MANIFEST /etc/sreinsights/job-types.json No The job types manifest of this image. See Job types manifest
SREINSIGHTS_PYTHON python3 No The interpreter python scripts run on with runtime: local
SREINSIGHTS_DOCKER docker No The Docker CLI used for runtime: docker scripts
LOG_LEVEL info No fatal, error, warn, info, debug, trace or silent

An empty value (VAR=) counts as not set, as Compose passes unset variables that way. A runner with an invalid setting does not start: it prints Invalid runner configuration: followed by one line per setting to fix.

Every runner reports two labels without configuration, so a monitor’s runsOn.labels: [linux, arm64] works out of the box:

Label Value
os linux, macos or windows
arch The processor, as Node reports it: x64, arm64

Add your own with SREINSIGHTS_RUNNER_LABELS. A run goes only to a runner that has every label the monitor or job asks for. See Runners.

The runner keeps its identity in runner.json inside SREINSIGHTS_RUNNER_STATE_DIR (default /var/lib/sreinsights-runner). The directory is created with mode 0700 and the file with mode 0600.

The file holds two private keys, generated on the runner: an Ed25519 key to sign in and an X25519 key to open the secrets sealed to it. SREInsights only ever sees the public halves.

If the file is missing and no token is set, the runner stops with:

This runner is not registered yet and /var/lib/sreinsights-runner/runner.json does not exist. Set SREINSIGHTS_REGISTRATION_TOKEN to a token from the Runners page in SREInsights.

On SIGTERM or SIGINT the runner stops taking work and gives running checks up to 30 seconds to finish. Docker’s default stop timeout is 10 seconds, which kills them, so always set:

  • --stop-timeout 40 with docker run
  • stop_grace_period: 40s in Compose
Exit code Meaning
0 Stopped cleanly
1 Invalid configuration, or the runner could not start (for example, no identity, or SREInsights refused it at start)
2 SREInsights cut the runner off while it was working: it was disabled, is unknown, or failed to sign in. Register it again with a new token

Run the container with:

--read-only --tmpfs /tmp --cap-drop ALL --security-opt no-new-privileges

Keep the /tmp tmpfs when you use --read-only: script checks write their code and output files there. The image holds one minified bundle and no source.

A runner that has no disk that survives, such as an AWS Lambda function, can’t keep a state directory. Register it once from any machine with Docker, using the identity command:

Terminal window
docker run --rm \
-e SREINSIGHTS_URL=https://console.sreinsights.com \
-e SREINSIGHTS_REGISTRATION_TOKEN=prt_… \
-e SREINSIGHTS_RUNNER_NAME=nightly-jobs \
ghcr.io/bintree-softwares/sreinsights-runner:latest identity

It generates the runner’s keys on that machine, registers the public halves, and prints one line starting with sri1.. That line is the runner’s identity: shown once, and only on stdout, so you can pipe it straight into a secret store. A message naming the runner and its group goes to stderr.

Whoever holds the identity is that runner. Store it in a secret, never in a file or a chat. If it leaks, disable the runner on the Runners page and register again. Connect function on a Lambda runner group gives you this command with the values filled in.

The runner as an AWS Lambda function (image deploy/Dockerfile.runner-lambda, handler sreinsights-runner-lambda.handler) reads a shorter list:

Variable Default Secret What it does
SREINSIGHTS_RUNNER_IDENTITY_SECRET Not set No Name or ARN of an AWS Secrets Manager secret holding the sri1.… line. The function’s role needs secretsmanager:GetSecretValue on it. A key/value secret works too: the pair named SREINSIGHTS_RUNNER_IDENTITY is used
SREINSIGHTS_RUNNER_IDENTITY Not set Yes The sri1.… line itself, when you don’t use a secret
SREINSIGHTS_URL The URL the runner was registered with No Where the function reaches SREInsights
SREINSIGHTS_RUNNER_HOSTED false No Hosted mode, for a hosted Lambda group. See Hosted mode
SREINSIGHTS_SCRIPT_ENV_PASSTHROUGH None No As for any runner. See What scripts inherit
SREINSIGHTS_JOB_TYPES_MANIFEST /etc/sreinsights/job-types.json No As for any runner
SREINSIGHTS_PYTHON python3 No As for any runner
LOG_LEVEL info No As for any runner

Set one of SREINSIGHTS_RUNNER_IDENTITY_SECRET or SREINSIGHTS_RUNNER_IDENTITY. Give the function a timeout of up to 900 seconds and set its retry attempts for asynchronous invocations to 0: SREInsights starts a run again itself when it needs to.

A run still going 20 seconds before the function’s timeout is stopped and reported as timeout. A function has no Docker daemon, so runtime: docker scripts are refused. See Lambda runner groups.

SREINSIGHTS_RUNNER_HOSTED=true is for runners an operator runs for every organization on an instance (see Hosted runner groups). Your own runners leave it off. In hosted mode, before its first connection, the runner:

  • Allows public addresses only. An egress guard refuses connections to private, loopback, link-local (cloud metadata), CGNAT, reserved, documentation and multicast ranges, for IPv4 and IPv6. Host names are resolved and checked at connect time, so DNS rebinding and redirects are covered. Unix sockets and UDP are refused. The one exception is the host and port in SREINSIGHTS_URL.
  • Runs no scripts. It doesn’t report the script capability and refuses a script run if one reaches it.
  • Gives checks and job types an empty environment. No variable on the host is read, SREINSIGHTS_SECRET_* included.
  • Ignores SREINSIGHTS_SCRIPT_ENV_PASSTHROUGH, and logs a warning if it is set.

A script check inherits a short fixed list of the runner’s environment, plus the check’s own env:

PATH, HOME, LANG, LC_ALL, TZ, TMPDIR, SSL_CERT_FILE, NODE_EXTRA_CA_CERTS, HTTPS_PROXY, HTTP_PROXY, NO_PROXY

Whoever deploys the runner can let runtime: local scripts inherit more with SREINSIGHTS_SCRIPT_ENV_PASSTHROUGH, a comma-separated list of variable names. A monitor can’t add to it. At start the runner logs the names it passes (never the values).

These are never passed, whatever the list says. The runner leaves them out and logs a warning:

  • SREINSIGHTS_SECRET_* (connection secrets kept on the runner)
  • SREINSIGHTS_REGISTRATION_TOKEN
  • SREINSIGHTS_RUNNER_IDENTITY and SREINSIGHTS_RUNNER_IDENTITY_SECRET

Scripts in a container (runtime: docker) get none of the list, and a hosted runner ignores it.

The common use is a Lambda runner whose job scripts must call AWS as the function’s role. Lambda puts the role only in the environment, so list its four variables:

SREINSIGHTS_SCRIPT_ENV_PASSTHROUGH=AWS_ACCESS_KEY_ID,AWS_SECRET_ACCESS_KEY,AWS_SESSION_TOKEN,AWS_REGION

A connection can keep its secrets on your runners instead of in SREInsights. The runner then reads each secret field from an environment variable named:

SREINSIGHTS_SECRET_<CONNECTION NAME>_<FIELD>

The connection name is upper-cased, with every run of other characters replaced by _. The field name goes from camelCase to upper snake case. For a connection named orders-db with a password field:

Terminal window
docker run … -e SREINSIGHTS_SECRET_ORDERS_DB_PASSWORD='…' ghcr.io/bintree-softwares/sreinsights-runner:latest

Hosted runners don’t support runner-local secrets. See Connections and secrets.

A runner image says which job types it provides in a manifest, /etc/sreinsights/job-types.json, or the file SREINSIGHTS_JOB_TYPES_MANIFEST names. The runner reads it at start and reports the types to SREInsights, so a job’s run goes only to a runner whose image provides its type.

  • An image without a manifest provides no job types.
  • A manifest that is named and missing or invalid stops the runner from starting.

The format, and what a job type’s command gets and must return, is in Job type contract.