> ## Documentation Index
> Fetch the complete documentation index at: https://snowglobe.so/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Environment variables

> Every environment variable the `snowglobe` CLI reads, organized from the few you'll set often to the advanced escape hatches.

`snowglobe` is configured through environment variables. They're
grouped into three layers so you can stop reading once you've found what
you need:

1. **Connection & auth** — the handful most setups touch.
2. **Throughput** — three top-level knobs that cover the common "go
   faster / wait longer / retry more" cases. Prefer these.
3. **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:

1. The built-in default (or, for an advanced knob, the value derived from
   a throughput knob).
2. A line in `.snowglobe/config.rc` (`KEY=value`, one per line). This
   file is created by `snowglobe init`.
3. An exported shell variable (`export KEY=value`) — always wins.

<Note>
  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.
</Note>

## 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](https://snowglobe.so/app/keys).                         |
| `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:

```bash theme={null}
export SNOWGLOBE_CLIENT_PORT=9000   # binds 9000 and self-calls http://localhost:9000
```

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:

```bash theme={null}
export SNOWGLOBE_CLIENT_URL=http://sidecar.internal:1234
```

<Warning>
  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`.
</Warning>

## 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. |

A higher-throughput run is usually a single line:

```bash theme={null}
export SNOWGLOBE_MAX_PARALLEL_COMPLETIONS=50
```

<Note>
  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.
</Note>

### 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<br />`COMPLETION_BATCH_SIZE` = N<br />`COMPLETIONS_PER_SECOND` = max(120, N × 60)<br />`COMPLETIONS_INTERVAL_SECONDS` = 60                 |
| `SNOWGLOBE_COMPLETION_TIMEOUT_SECONDS` = T | `REQUEST_TIMEOUT_SECONDS` = T<br />`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)<br />`SNOWGLOBE_HTTP_RETRY_BASE_SECONDS` = 1.0<br />`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.                                                                                                                               |

<Tip>
  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.
</Tip>

### 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.                                  |