Skip to content

Operator commands

Operator commands manage the parts of a self-hosted instance that have no page in the web app, or that you want to set up without anyone signing in. They run with the system database role, where the control plane runs. This page covers each command, where to run it, and hosted runner groups.

Command What it does
sreinsights runners … Creates and manages hosted runner groups, which every organization can use
sreinsights connections import Creates or updates a connection from an AWS Secrets Manager secret, without anyone seeing its values
sreinsights clients list Prints an organization’s id and its clients’ ids, names and destination prefixes
sreinsights syncs … Creates, previews and switches on an organization’s syncs from JSON

The server image’s entrypoint (deploy/docker-entrypoint.sh, installed as /usr/local/bin/sreinsights) takes the command as its first argument. Run it in the app container:

Terminal window
docker compose exec app sreinsights runners list
docker compose exec app sreinsights clients list --org acme

With the Docker Compose deployment, add -f docker-compose.coolify.yml. With the EC2 deployment, run it from deploy/ec2/.

Each command needs these settings, which the app container already has:

Command Needs
runners SYSTEM_DATABASE_URL. SREINSIGHTS_API_URL (or SREINSIGHTS_BASE_URL) and SREINSIGHTS_RUNNER_IMAGE fill in the install command it prints
connections SYSTEM_DATABASE_URL, SREINSIGHTS_MASTER_KEY, and AWS credentials that may read the secret
clients SYSTEM_DATABASE_URL
syncs SYSTEM_DATABASE_URL

From the repository root, with the settings in .env:

Terminal window
npm run runners -w @sreinsights/server -- list
npm run connections -w @sreinsights/server -- import --org acme …
npm run clients -w @sreinsights/server -- list --org acme
npm run syncs -w @sreinsights/server -- status --org acme

A serverless instance has no shell to run them in. The migrate function runs connections, clients and syncs instead: it has the system connection and the master key. Invoke it with the command’s arguments as a list of strings under the command’s name:

Terminal window
aws lambda invoke --function-name <name>-migrate --cli-binary-format raw-in-base64-out \
--payload '{"clients":["list","--org","acme"]}' out.json && cat out.json

The answer is { "lines": [...] }, what the command would print. A refused command fails the invocation with the reason: the FunctionError and the error message in out.json. Any other event, such as the deploy’s own, runs the migrations and the seed.

Terminal window
# A connection from a Secrets Manager secret, in one client.
aws lambda invoke --function-name <name>-migrate --cli-binary-format raw-in-base64-out \
--payload '{"connections":["import","--org","acme","--client","Acme Retail","--type","s3_destination","--name","Acme Retail lake","--set","bucket=<bucket>,prefix=orgs/<org id>/clients/<client id>/,region=us-east-1","--from-secret","arn:aws:secretsmanager:us-east-1:123456789012:secret:acme/lake-AbCdEf","--map","accessKeyId=AWS_ACCESS_KEY_ID,secretAccessKey=AWS_SECRET_ACCESS_KEY"]}' out.json && cat out.json
# Syncs: apply, then preview, status and enable.
aws lambda invoke --function-name <name>-migrate --cli-binary-format raw-in-base64-out \
--payload '{"syncs":["status","--org","acme"]}' out.json && cat out.json
  • For connections import, the migrate function’s role must be able to read the secret. Add the secret’s ARN to connection_import_secret_arns, apply, run the import, then remove the ARN and apply again.
  • syncs needs nothing beyond what the function has.
  • Whoever may invoke the migrate function may run these commands. That is already who may change the schema, so keep lambda:InvokeFunction on it to your operators.
  • runners is not available through the migrate function.

Hosted runner groups have no UI: they belong to no organization, so only this command creates and changes them. See Hosted runner groups for what they are.

Terminal window
sreinsights runners list
sreinsights runners add fra-1 --location "Frankfurt, Germany"
sreinsights runners add jobs-us --location "Ohio, United States" --lambda sreinsights-runner-jobs --region us-east-2
sreinsights runners token fra-1 --uses 2 --hours 24
sreinsights runners disable <runner-id>
sreinsights runners remove fra-1
Subcommand Options What it does
list Each hosted group with its location, runners online (or its Lambda function), and how many monitors and jobs use it. Under each, its runners: id, name, version, status and when last seen
add <group> --location "<text>" (required), --description "<text>", --lambda <function name or ARN> --region <aws-region> Creates a hosted group. Customers choose hosted groups by location. With --lambda and --region, it is a hosted Lambda group
token <group> --uses <1–50> (default 1), --hours <1–168> (default 24) Prints a registration token once, with a ready docker run command, or for a Lambda group the identity command
disable <runner-id> Cuts a hosted runner off. Its open leases go back to the group at once
remove <group> Deletes the group with its runners and tokens. Refused while any organization’s monitor or job still runs on it

A group name uses lower-case letters, digits, ., _ or -. Hosted group names are unique. runners --help prints the usage.

Run the runner image with hosted mode on and the token from runners token. The printed command looks like this:

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

Or use the repository’s deploy/compose.hosted-runner.yml, which runs it read-only, with a tmpfs /tmp, all capabilities dropped, no-new-privileges and a network of its own:

Terminal window
SREINSIGHTS_URL=https://sreinsights.example.com SREINSIGHTS_REGISTRATION_TOKEN=prt_… \
docker compose -f compose.hosted-runner.yml -p sreinsights-hosted-fra-1 up -d
  • Point SREINSIGHTS_URL at the control plane’s public URL. The hosted runner’s egress guard allows only that host and port among private addresses.
  • Mount a persistent volume for its identity, so redeploys need no new token.
  • Give it no domain and no published ports. It only connects out.

Creates or updates a connection from an AWS Secrets Manager secret, so nobody types, sees or pastes its values. It encrypts exactly as a connection saved through the API does.

Terminal window
sreinsights connections import --org acme --type shopify_admin --name "Acme store" \
--from-secret arn:aws:secretsmanager:us-east-1:123456789012:secret:acme/shopify-AbCdEf \
--map accessToken=SHOPIFY_ACCESS_TOKEN,shopDomain=SHOPIFY_STORE_DOMAIN
sreinsights connections import --org acme --type google_service_account --name "Google" \
--from-secret arn:aws:secretsmanager:us-east-1:123456789012:secret:acme/google-key-AbCdEf --map key=@
sreinsights connections import --org acme --client "Acme Retail" --type s3_destination --name "Acme Retail lake" \
--set bucket=acme-lake,prefix=orgs/<org id>/clients/<client id>/,region=us-east-1 \
--from-secret arn:aws:secretsmanager:us-east-1:123456789012:secret:acme/lake-AbCdEf \
--map accessKeyId=AWS_ACCESS_KEY_ID,secretAccessKey=AWS_SECRET_ACCESS_KEY
Option Required What it does
--org <id or slug> Yes The organization
--type <type> Yes The connection type. See Connection types
--name <name> Yes The connection’s name. Importing again into the same organization and name updates that connection
--from-secret <name or ARN> With --map The Secrets Manager secret to read
--map <field>=<KEY>,… No Takes each field from a key of the secret (a JSON object of keys). <field>=@ takes the whole secret, such as a service account’s JSON key file
--set <field>=<value>,… No Fields that are not secret, such as a bucket or a region. A secret field here is refused
--client <id or name> No Puts the connection in one of the organization’s clients. none makes it shared. Left out, a new connection is shared and an existing one stays where it is
--description "<text>" No The connection’s description

--map and --set can also be given more than once.

  • Checked like a new connection. Unknown fields are refused, and required fields and shapes are checked.
  • Idempotent by organization and name. Importing again overwrites the fields it names and keeps the rest, so you can import fields from two secrets, or settings and a secret, one after the other. A name already used by a connection of another type is refused.
  • Moving a connection to another client follows the API’s rule: it is refused while a job or monitor that couldn’t use it there still does.
  • No values in the output. It prints the connection’s id, its client, and the names of the fields it set. Errors name fields and secret keys, never values.
Created s3_destination connection "Acme Retail lake" in acme: 6f1c…
Client: Acme Retail (2b7e…).
From the secret: accessKeyId, secretAccessKey.
Set: bucket, prefix, region.
Secret fields stored, encrypted: accessKeyId, secretAccessKey. No value is shown.

Read-only. Prints the organization’s id, the prefix its own jobs write under, then one line per client: its id, name and destination prefix. Use it to build destination connections and IAM policies. Clients themselves are made on the Clients page.

Terminal window
sreinsights clients list --org acme
Organization acme ("Acme"): <org id>
its own jobs (no client) write under orgs/<org id>/
<client id> Acme Retail · orgs/<org id>/clients/<client id>/

--org takes the organization’s slug or id. See Clients.

Sets up an organization’s syncs from JSON, without anyone signing in. It applies the API’s checks (spec, connections by name, client rules, schedule), writes the audit log as the system, and prints names, counts and reasons, never a connection’s values.

Terminal window
sreinsights syncs apply --org acme --json '[{ "name": "Orders", "group": "default", … }]' # create paused, or update by name
sreinsights syncs preview --org acme --name "Orders" # queue a preview on the sync's runners
sreinsights syncs status --org acme [--name "Orders"] # each sync, and what its latest preview found
sreinsights syncs enable --org acme --name "Orders" # only once this version has been previewed

--json is a list of syncs. Each item takes:

Field Type Required Default What it is
name string Yes The sync’s name. apply updates the sync with this name, or creates it
description string No
client string No The organization’s own A client’s name
group string Yes One of the organization’s runner groups
schedule object Yes { "cron": "…", "timezone": "UTC" }. Held to the instance’s shortest interval
timeoutMs integer No 600000 From 10000 to 900000
alerting object No { "onFailure": true, "freshnessHours": null, "severity": "high" } When the sync’s runs raise alerts
source string No The source connection’s name. Leave it out for a sheet read by its public link
destination string Yes The destination connection’s name
sync object Yes The spec. See Sync spec

A new sync is created paused. Preview it, check status, then enable it. A changed spec or connection pauses the sync at a new version, as in the API, and enable refuses until that version has been previewed.

Hosted runner groups are runners you operate for every organization on your instance. With them, organizations can monitor targets reachable from the internet without running a runner of their own. They add to self-hosted runners and don’t replace them: each monitor picks one or the other.

Organization’s own runner Hosted runner
Operated by The organization, inside its network You, the operator
Takes work from Its own organization Every organization that targets its group
Check types All All except scripts
Private addresses Allowed Blocked
Secrets kept on the runner host Allowed Not supported
Plan limits None Monitor count, job count, shortest interval
Kind Polling or Lambda Polling, or Lambda when the operator makes it so

Organizations see hosted groups by location: in the monitor form’s runner group list, in a read-only section of the Runners page, and through GET /api/v1/hosted-runner-groups. They never see a hosted runner’s name, host or version. Each run’s connection secrets are opened with the run’s own organization and sealed to the runner for that one lease.

Saving a monitor or job on a hosted group checks the organization’s plan:

Plan Shortest interval (min_interval_s) Monitors on hosted runners (hosted_monitors) Jobs on hosted runners (hosted_jobs)
Starter 300 s 10 5
Team 60 s 100 50
Business 30 s 1,000 500
  • Scripts are refused, including script steps in flows: 400 HOSTED_SCRIPT_NOT_ALLOWED.
  • Connections whose secrets are kept on customer runners are refused: 400 HOSTED_RUNNER_LOCAL_SECRETS.
  • A job must name a destination connection.
  • A broken limit returns 403 PLAN_LIMIT. Jobs count apart from monitors. Saving one that is already on the group doesn’t count it twice.

Monitors on an organization’s own runners have no count or interval limit beyond the platform’s 30-second floor.

An offline hosted group raises no alert in any organization. The runner watch logs hosted runner group is offline instead, for you to alert on.

A hosted group can be a Lambda group: no runner stays up, and each run invokes one function you operate. It suits data jobs, which run once a day for minutes. Organizations still can’t create a Lambda group on a shared instance or name a function: only runners add … --lambda does.

Terminal window
sreinsights runners add jobs-us --location "Ohio, United States" --lambda sreinsights-runner-jobs --region us-east-2
sreinsights runners token jobs-us # prints the identity command for the function instead of docker run

The control plane needs:

Setting What it does
SREINSIGHTS_HOSTED_LAMBDA_RUNNERS=true Invokes the functions of hosted Lambda groups, and no organization’s own Lambda group. Safe where SREINSIGHTS_LAMBDA_RUNNERS is not, because no organization chooses the function
SREINSIGHTS_LAMBDA_FUNCTION_PREFIXES Names a function must start with to be invoked, for every Lambda group, for example sreinsights-runner-. A run on any other function ends as error/dispatch_failed with the reason. The serverless configuration sets it to the instance’s <name>-runner-

The function needs SREINSIGHTS_RUNNER_HOSTED=true. In hosted mode it installs the egress guard before its first connection, runs no scripts, gives checks and job types an empty environment (so the function’s own role reaches no run), and ignores SREINSIGHTS_SCRIPT_ENV_PASSTHROUGH. Register it with the identity command that runners token prints, and store the identity in the function’s secret. See Runner settings.

On the Runners page a hosted Lambda location shows as online: it has no runner between runs.