snowglobe is configured through environment variables. They’re
grouped into three layers so you can stop reading once you’ve found what
you need:
- Connection & auth — the handful most setups touch.
- Throughput — three top-level knobs that cover the common “go
faster / wait longer / retry more” cases. Prefer these.
- Advanced — the per-feature knobs the throughput knobs derive. Set
these directly only when you have a specific reason.
Where to set them
Any of these work; later sources win over earlier ones:
- The built-in default (or, for an advanced knob, the value derived from
a throughput knob).
- A line in
.snowglobe/config.rc (KEY=value, one per line). This
file is created by snowglobe init.
- An exported shell variable (
export KEY=value) — always wins.
Values in .snowglobe/config.rc are loaded into the environment at
startup, so a line in that file behaves exactly like exporting the
variable in your shell.
Connection & auth
| Variable | Default | What it does |
|---|
SNOWGLOBE_API_KEY (or GUARDRAILS_API_KEY) | required | API key for all Snowglobe requests. Get one from the dashboard. |
CONTROL_PLANE_URL | https://api.snowglobe.guardrailsai.com | Snowglobe API base URL. Override only when pointing at a preview environment. |
SNOWGLOBE_APP_ID | (none) | Single-agent app-id override. Multi-agent projects use .snowglobe/agents.json instead. |
SNOWGLOBE_CLIENT_PORT | 8000 | Port the wrapper’s local server binds. The single source of truth for the port — see below. |
SNOWGLOBE_CLIENT_URL | http://localhost:<SNOWGLOBE_CLIENT_PORT> | Advanced override for the URL the wrapper uses to reach its own local server. Leave unset on a normal single-host setup. |
Changing the port
The wrapper runs a local server (bound to SNOWGLOBE_CLIENT_PORT) and
then calls itself over HTTP to drive completions. The URL it uses,
SNOWGLOBE_CLIENT_URL, defaults to http://localhost:<SNOWGLOBE_CLIENT_PORT>,
so to move the server you set only the port:
Set SNOWGLOBE_CLIENT_URL explicitly only for the unusual case where
the wrapper’s server is reached on a different host or through a proxy:
Don’t set the port inside SNOWGLOBE_CLIENT_URL while also setting
SNOWGLOBE_CLIENT_PORT to a different value — the wrapper would bind
one port and call another. Set the port once via
SNOWGLOBE_CLIENT_PORT.
Throughput
These three knobs cover what most users want to tune. Set one and the
CLI derives a consistent set of advanced values for you (any advanced
variable you set explicitly still wins).
| Variable | Default | Use it to… |
|---|
SNOWGLOBE_MAX_PARALLEL_COMPLETIONS | 10 | Control how many completions run in parallel. |
SNOWGLOBE_COMPLETION_TIMEOUT_SECONDS | 300 | Control how long a single completion may take. |
SNOWGLOBE_COMPLETION_RETRIES | 2 | Control how many times a failed completion is retried. |
At startup the CLI checks your values against Snowglobe’s server-side
ceilings and prints a one-line warning (non-fatal) if one is too high —
for example a completion timeout longer than upstream services honor.
What each knob derives
If you need to understand or override the underlying behavior, here’s the
mapping:
| Throughput knob | Derived advanced variables |
|---|
SNOWGLOBE_MAX_PARALLEL_COMPLETIONS = N | SNOWGLOBE_COMPLETION_DISPATCH_CONCURRENCY = N
COMPLETION_BATCH_SIZE = N
COMPLETIONS_PER_SECOND = max(120, N × 60)
COMPLETIONS_INTERVAL_SECONDS = 60 |
SNOWGLOBE_COMPLETION_TIMEOUT_SECONDS = T | REQUEST_TIMEOUT_SECONDS = T
SNOWGLOBE_INFLIGHT_TEST_TTL_SECONDS = max(T × 2, 600) |
SNOWGLOBE_COMPLETION_RETRIES = R | SNOWGLOBE_HTTP_RETRY_ATTEMPTS = R + 1 (the initial call counts as an attempt)
SNOWGLOBE_HTTP_RETRY_BASE_SECONDS = 1.0
SNOWGLOBE_HTTP_RETRY_MAX_SECONDS = max(15, T × 0.05) |
Advanced
Set these directly only when the throughput knobs don’t give you the
shape you need. They are process-wide, not per-agent: one wrapper
serving three agents shares one set of limits.
Dispatch & rate limiting
| Variable | Default | What it does |
|---|
SNOWGLOBE_COMPLETION_DISPATCH_CONCURRENCY | derived | How many completions dispatch in parallel. |
COMPLETION_BATCH_SIZE | derived | Test rows pulled per experiment per poll tick. |
COMPLETIONS_PER_SECOND | derived | Deprecated, misnamed. Max inbound completion requests per COMPLETIONS_INTERVAL_SECONDS window (not literally per-second). Prefer SNOWGLOBE_MAX_PARALLEL_COMPLETIONS. |
COMPLETIONS_INTERVAL_SECONDS | 60 | Window length for the rate limit above. |
CONCURRENT_RISK_EVALUATIONS | 120 | Max inbound risk-evaluation requests per its window. |
CONCURRENT_RISK_EVALUATIONS_INTERVAL_SECONDS | 60 | Window length for the risk-evaluation limiter. |
Raise dispatch concurrency and the inbound rate limit together. As a
rule of thumb keep COMPLETIONS_PER_SECOND ≥ COMPLETION_BATCH_SIZE × 5,
or self-dispatched completions get rate-limited under bursty polling.
Using the SNOWGLOBE_MAX_PARALLEL_COMPLETIONS knob keeps this ratio
correct automatically.
Timeouts & retries
| Variable | Default | What it does |
|---|
REQUEST_TIMEOUT_SECONDS | derived | Per-request timeout for every Snowglobe call and every outbound completion. |
SNOWGLOBE_INFLIGHT_TEST_TTL_SECONDS | derived | How long a test stays “in-flight” before the wrapper re-pulls it as stale. |
SNOWGLOBE_HTTP_RETRY_ATTEMPTS | derived | Total attempts (initial call + retries) on transient failures. 1 disables retry. |
SNOWGLOBE_HTTP_RETRY_BASE_SECONDS | 1.0 | Base for exponential backoff between retries. |
SNOWGLOBE_HTTP_RETRY_MAX_SECONDS | derived | Cap on backoff delay per retry. |
Polling & heartbeat
| Variable | Default | What it does |
|---|
SNOWGLOBE_APPLICATION_HEARTBEAT_INTERVAL_MINUTES | 5 | How often the wrapper reports liveness to Snowglobe. Changing this affects whether the dashboard sees the wrapper as online — leave at the default unless advised otherwise. |
SNOWGLOBE_REPORT_INTERVAL_TICKS | 15 | Poll ticks between progress-summary log lines. |
SNOWGLOBE_TOOL_POLL_TIMEOUT_SECONDS | 300.0 | Max wait for a mocked tool response from Snowglobe (when simulating with tools). |
SNOWGLOBE_TOOL_POLL_INTERVAL_SECONDS | 1.0 | Sleep between tool-poll iterations (floored at 0.1). |
Misc
| Variable | Default | What it does |
|---|
SNOWGLOBE_AUTH_CONFIGURE_PORT | 9011 | Local port the CLI binds during the browser-based snowglobe login flow. |
DEBUG | false | Set to true for verbose debug logging. |