Configuration — Nistor Docs

Nistor is configured in two places: the environment of each process (where it runs, which database, secrets) and the API (what it observes: connections, rules, alerts, contracts). Prefer the second for anything that is data.

Environment variables#

Operator-facing variables are prefixed NISTOR_. The database uses the standard POSTGRES_ names.

Variable	Meaning
`POSTGRES_SERVER`, `POSTGRES_PORT`, `POSTGRES_DB`, `POSTGRES_USER`, `POSTGRES_PASSWORD`	the PostgreSQL database every role shares
`ENVIRONMENT`	`local`, `dev`, `test` or `prod`; `dev`, `test` and `prod` enforce OIDC authentication, `test` and `prod` also trusted hosts, `prod` hides the API docs; `local` relaxes these
`NISTOR_INSTANCE`	the deployment's name, the suffix of its resource names (`nistor-backend-<instance>`, its Cloud Scheduler jobs and buckets, `mstr-password-<instance>`); Terraform sets it on every role from the composition's `instance`. Unset, it is `ENVIRONMENT`, which stays the tier
`PORT`	the port a role listens on (default 8080)
`NISTOR_ROLE`	read by the backend only: `web` (default) or `jobs`
`NISTOR_API_URL`, `NISTOR_API_TOKEN`	the CLI's backend URL and bearer token (also `--api-url`, `--token`)
`NISTOR_BACKEND_URL`	the backend's URL
`NISTOR_URL`	the public URL of Nistor, used in notification links and OIDC redirects
`SCHEDULER_URL`, `COMPILER_URL`, `INPUT_LOGS_URL`, `FRONTEND_URL`, `NISTOR_JOBS_URL`	where roles find each other (the first four have no prefix)
`NISTOR_CONN_SECRET__<id>`	the secret a connection references as `env://<id>`; the alternative is a cloud secret manager
`NISTOR_TOOL_LIMIT_<KEY>`	slots per process for a tool capacity key, `gcp.bigquery` becomes `NISTOR_TOOL_LIMIT_GCP_BIGQUERY`; `0` is unbounded
`NISTOR_TOOL_ACQUIRE_TIMEOUT_SECONDS`, `NISTOR_TOOL_CAPACITY_HEARTBEAT`	how long a task waits for a slot; the capacity heartbeat
`NISTOR_PLUGIN_VALIDATION`	`warn` (default) or `strict`: an executor plugin failing validation stops startup instead of only being logged
`NISTOR_RATE_OVERRIDES`	JSON list of price overrides for cost estimates; a malformed value is ignored
`NISTOR_GRAPH_SWAP_ENABLED`	build the graph aside and swap it in (default on)
`WEBHOOK_REQUIRE_TIMESTAMP`	backend: `true` makes the signed `X-Webhook-Timestamp` mandatory for generic webhook endpoints (default off; see webhooks)
`NISTOR_MASTER_GRAPH_PRELOAD`	opt in to loading the graph in the server's master process
`NISTOR_ALLOW_LIVE_MIGRATION`	set to `1` to confirm a migration against a deployed database (a safety guard otherwise refuses)
`NISTOR_MCP_BASE_URL`, `NISTOR_MCP_TOKEN`	the MCP server's backend URL and bearer token
`NISTOR_DISPLAY_TIME_ZONE`	read by the web container at start: the time zone the UI shows times in and its date pickers speak, any IANA name (`Europe/Paris`, `America/New_York`); `UTC` when unset or not a zone name. A web build can set a default with `REACT_APP_DISPLAY_TIME_ZONE`. On GCP the reference root's `frontend_display_time_zone` (the frontend module's `display_time_zone`) sets it

Never put a secret in a file you commit. Use a secret manager, or the NISTOR_CONN_SECRET__ form for local use.

The CLI#

nistor talks to the backend. Give it --api-url and --token, or the variables above.

Command	Does
`nistor serve`	run a server role
`nistor migrate`	apply the database migrations
`nistor auth test`	check connectivity and credentials
`nistor rules sync`, `list`, `validate`	manage scheduling rules kept as files
`nistor alerts sync`, `list`	alert channels and policies
`nistor odcs sync`	data contracts kept as `*.odcs.yaml`
`nistor patterns sync`, `list`	resource patterns
`nistor env-mapping sync`, `show`	environment mappings
`nistor compiler sync`, `show`	compiler configuration
`nistor admin ...`	users, permissions and the audit log
`nistor tool new <id>`	scaffold a tool, see Writing a tool
`nistor release ...`	release tooling for maintainers

Run nistor <command> --help for the options. CLI explains how to install it and is its reference.

Connections and tools#

Each tool you use needs a connection: its configuration and a reference to its secrets. Create connections through the web shell or the API, then test them; the test runs the tool's health probe.