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.
Run it with Docker
Section titled “Run it with Docker”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:
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:latestOn a self-hosted instance, use <your SREInsights URL> for SREINSIGHTS_URL.
Run it with Docker Compose
Section titled “Run it with Docker Compose”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:
export SREINSIGHTS_URL=https://console.sreinsights.comexport SREINSIGHTS_REGISTRATION_TOKEN=prt_… # from the Runners page; needed on first start onlydocker compose -f compose.runner.yml up -dRun two or more runners, on different hosts, in the same runner group for redundancy.
Environment variables
Section titled “Environment variables”| 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.
Labels
Section titled “Labels”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.
State directory
Section titled “State directory”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.Stopping
Section titled “Stopping”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 40withdocker runstop_grace_period: 40sin 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 |
Hardening
Section titled “Hardening”Run the container with:
--read-only --tmpfs /tmp --cap-drop ALL --security-opt no-new-privilegesKeep 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.
The identity command
Section titled “The identity command”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:
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 identityIt 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.
Lambda runner settings
Section titled “Lambda runner settings”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.
Hosted mode
Section titled “Hosted mode”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.
What scripts inherit
Section titled “What scripts inherit”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_TOKENSREINSIGHTS_RUNNER_IDENTITYandSREINSIGHTS_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_REGIONSecrets kept on the runner
Section titled “Secrets kept on the runner”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:
docker run … -e SREINSIGHTS_SECRET_ORDERS_DB_PASSWORD='…' ghcr.io/bintree-softwares/sreinsights-runner:latestHosted runners don’t support runner-local secrets. See Connections and secrets.
Job types manifest
Section titled “Job types manifest”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.