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 |
Where to run them
Section titled “Where to run them”In the server image
Section titled “In the server image”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:
docker compose exec app sreinsights runners listdocker compose exec app sreinsights clients list --org acmeWith 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 a checkout
Section titled “From a checkout”From the repository root, with the settings in .env:
npm run runners -w @sreinsights/server -- listnpm run connections -w @sreinsights/server -- import --org acme …npm run clients -w @sreinsights/server -- list --org acmenpm run syncs -w @sreinsights/server -- status --org acmeOn a serverless instance
Section titled “On a serverless instance”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:
aws lambda invoke --function-name <name>-migrate --cli-binary-format raw-in-base64-out \ --payload '{"clients":["list","--org","acme"]}' out.json && cat out.jsonThe 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.
# 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 toconnection_import_secret_arns, apply, run the import, then remove the ARN and apply again. syncsneeds 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:InvokeFunctionon it to your operators. runnersis not available through the migrate function.
runners
Section titled “runners”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.
sreinsights runners listsreinsights runners add fra-1 --location "Frankfurt, Germany"sreinsights runners add jobs-us --location "Ohio, United States" --lambda sreinsights-runner-jobs --region us-east-2sreinsights runners token fra-1 --uses 2 --hours 24sreinsights 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.
Deploy a hosted runner
Section titled “Deploy a hosted runner”Run the runner image with hosted mode on and the token from runners token. The printed command looks like this:
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:latestOr 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:
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_URLat 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.
connections import
Section titled “connections import”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.
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.clients list
Section titled “clients list”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.
sreinsights clients list --org acmeOrganization 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.
sreinsights syncs apply --org acme --json '[{ "name": "Orders", "group": "default", … }]' # create paused, or update by namesreinsights syncs preview --org acme --name "Orders" # queue a preview on the sync's runnerssreinsights syncs status --org acme [--name "Orders"] # each sync, and what its latest preview foundsreinsights 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
Section titled “Hosted runner groups”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.
Plan limits
Section titled “Plan limits”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.
Offline hosted groups
Section titled “Offline hosted groups”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.
Hosted Lambda groups
Section titled “Hosted Lambda groups”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.
sreinsights runners add jobs-us --location "Ohio, United States" --lambda sreinsights-runner-jobs --region us-east-2sreinsights runners token jobs-us # prints the identity command for the function instead of docker runThe 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.