Runtime Environment Variables

These environment variables configure the local simpcat tools: the simpcat CLI, the Python SDK, and the per-run reporter started by simpcat.init(). They are not deployment-time environment variables for the Simpcat service.

Set them in the shell where you run either:

simpcat ...
python train.py

Users do not normally invoke simpcat reporter directly. The Python SDK starts a reporter subprocess for each run, and that subprocess inherits the environment of the training process.

All environment variables are optional.

Precedence

CLI commands: command flag > env var > config file > default
Python SDK: explicit function or constructor arguments win over env vars when both exist
Reporter settings: env var > [reporter] config file value > default

There is not one global precedence rule for every surface. For example, simpcat.Api(host="...") beats SIMPCAT_HOST, while simpcat runs --host ... also beats SIMPCAT_HOST.

Authentication & Connection

`SIMPCAT_HOST`

Target server host.

export SIMPCAT_HOST=my-simpcat.example.com

Default (CLI and spawned reporter): app.simpcat.ai
Default (Python Api and run URL helpers): simpcat.ai
Used by: CLI, Python SDK, spawned reporter
CLI precedence: --host > SIMPCAT_HOST > default
Python precedence: explicit host= argument > SIMPCAT_HOST > default
Strips https:// prefix and trailing / automatically

`SIMPCAT_API_KEY`

API key for authentication.

export SIMPCAT_API_KEY=sk-your-api-key

Used by: authenticated CLI commands, Python Api(...), spawned reporter
CLI precedence: SIMPCAT_API_KEY > per-host config entry [hosts."<host>"] > error
Python precedence: explicit api_key= argument > SIMPCAT_API_KEY > per-host config entry > error

`WANDB_API_KEY`

Weights & Biases API key for W&B export/import commands.

export WANDB_API_KEY=wandb-your-api-key

Used by: simpcat export wandb; W&B import flows that need to read W&B directly
Precedence: --api-key > WANDB_API_KEY > ~/.netrc

Configuration

`SIMPCAT_CONFIG`

Path to a specific config file (TOML).

export SIMPCAT_CONFIG=/path/to/simpcat.toml

Default resolution order: explicit path > SIMPCAT_CONFIG > walk up from CWD for simpcat.toml > ~/.simpcat/config.toml

`SIMPCAT_MODE`

Reporter operating mode: online or offline.

SIMPCAT_MODE=offline python train.py

Set this before starting training; the spawned reporter inherits it
Default: online
online — metrics uploaded in real-time
offline — metrics saved to local WAL only; upload later with simpcat sync
Offline resume limitation: fresh offline runs do not get run.json until future offline-resume support is added; multiple offline restarts are not merged into one logical run
Scope: reporter only
Not the same as: simpcat.init(mode="disabled"), which disables the SDK entirely
Precedence: SIMPCAT_MODE > [reporter].mode in config file > online

`SIMPCAT_RUN_DATA_DIR`

Override the local simpcat run-data directory location.

export SIMPCAT_RUN_DATA_DIR=/data/simpcat-runs

Used by: Python SDK (simpcat.init()), CLI (simpcat sync)
Meaning: this points at the local run-data root, not at a single run directory
Default (Python SDK): creates .simpcat/ in the current working directory, or dir/simpcat when simpcat.init(dir=...) / SimpCatLogger(save_dir=...) is used
Default (CLI simpcat sync): walks upward from the current working directory looking for an existing .simpcat/ or simpcat/; errors if none is found
CLI note: when SIMPCAT_RUN_DATA_DIR is set, simpcat sync uses it only if that directory already exists

`SIMPCAT_LOCAL_DIR`

Override the local runtime root for remote dir / save_dir values such as s3://.... Durable run identity is still read from and written to the remote <save_dir>/simpcat/run.json; sockets and reporter runtime files stay local. When unset, remote runtime files use the default local run-data root (.simpcat/ in the current working directory).

export SIMPCAT_LOCAL_DIR=/data/local-simpcat-runtime

Run Behavior

`SIMPCAT_RESUME`

Default resume mode for simpcat.init() when resume= is not passed explicitly.

SIMPCAT_RESUME=auto python train.py

Values: true/1 (same as "allow"), false/0 (fresh run), must, allow, never, auto
Default: not set; the SDK uses auto mode (resume from run.json when present, otherwise start a fresh run)
Used by: Python SDK (simpcat.init())
Precedence: explicit resume= argument > SIMPCAT_RESUME > SDK default

`SIMPCAT_RUN_ID`

Unsupported. SimpCat assigns run IDs and stores the durable ID in run.json under the run-data directory. To resume a run, reuse the same dir / save_dir so the SDK can read that file.

Used by: Python SDK rejects this variable during simpcat.init()
Replacement: reuse the same run-data directory with default auto-resume

Reporter Tuning

`SIMPCAT_REPORTER_FLUSH_INTERVAL_SECS`

How often (in seconds) the spawned reporter flushes batched metrics to the server.

export SIMPCAT_REPORTER_FLUSH_INTERVAL_SECS=10

Set before: python train.py
Default: 15
Precedence: env var > [reporter].flush_interval_secs in config file > 15
Most users: do not need this

`SIMPCAT_REPORTER_SNAPSHOT_INTERVAL_SECS`

How often (in seconds) the reporter writes local run snapshots.

export SIMPCAT_REPORTER_SNAPSHOT_INTERVAL_SECS=10

Set before: python train.py
Default: 10
Precedence: env var > [reporter].snapshot_interval_secs in config file > 10
Most users: do not need this

`SIMPCAT_REPORTER_MAX_BATCH_ROWS`

Maximum number of metric rows per flush batch.

export SIMPCAT_REPORTER_MAX_BATCH_ROWS=50000

Set before: python train.py
Default: 10000
Precedence: env var > [reporter].max_batch_rows in config file > 10000
Most users: do not need this

`SIMPCAT_REPORTER_MAX_BATCH_BYTES`

Maximum encoded metric payload size per flush batch.

export SIMPCAT_REPORTER_MAX_BATCH_BYTES=1048576

Set before: python train.py
Default: 1048576
Precedence: env var > [reporter].max_batch_bytes in config file > 1048576
Most users: do not need this

`SIMPCAT_REPORTER_MAX_HISTOGRAM_POINTS`

Maximum number of histogram buckets retained per histogram payload.

export SIMPCAT_REPORTER_MAX_HISTOGRAM_POINTS=32

Set before: python train.py
Default: 32
Precedence: env var > [reporter].max_histogram_points in config file > 32
Most users: do not need this

`SIMPCAT_REPORTER_MAX_HISTOGRAM_BYTES`

Maximum encoded histogram payload size per histogram batch.

export SIMPCAT_REPORTER_MAX_HISTOGRAM_BYTES=524288

Set before: python train.py
Default: 524288
Precedence: env var > [reporter].max_histogram_bytes in config file > 524288
Most users: do not need this

Endpoint Overrides

`SIMPCAT_METRICS_URL`

Override the derived metrics endpoint URL (normally derived from host via subdomain).

export SIMPCAT_METRICS_URL=http://localhost:8787/v1/metrics

Default: derived from SIMPCAT_HOST (e.g. https://metrics.simpcat.ai)
Used by: CLI (metric, metrics, export), Python SDK (Api)

`SIMPCAT_ASSETS_URL`

Override the derived assets endpoint URL.

export SIMPCAT_ASSETS_URL=http://localhost:8787/v1/assets

Default: derived from SIMPCAT_HOST (e.g. https://assets.simpcat.ai)
Used by: CLI, Python SDK (Api)

`SIMPCAT_METADATA_URL`

Override the derived metadata endpoint URL.

export SIMPCAT_METADATA_URL=http://localhost:8787/v1/metadata

Default: derived from SIMPCAT_HOST (e.g. https://metadata.simpcat.ai)
Used by: CLI, Python SDK (Api)

`SIMPCAT_INIT_TIMEOUT`

Timeout in seconds for the Python SDK to wait for the reporter to initialize.

export SIMPCAT_INIT_TIMEOUT=30

Default: 10
Used by: Python SDK (simpcat.init())

Development & Debugging

`SIMPCAT_COMMAND`

Command to run the simpcat CLI. Can be a path to a binary or a multi-arg command (like GIT_SSH_COMMAND), split with shell quoting rules.

export SIMPCAT_COMMAND=/usr/local/bin/simpcat
# or use cargo run to always compile from source:
export SIMPCAT_COMMAND="cargo run --bin simpcat --manifest-path /path/to/reporter/Cargo.toml --release --"

Default: looks for simpcat on $PATH
Used by: Python SDK (simpcat.init(), simpcat.login())

`SIMPCAT_LOG_FILTER`

Controls logging for the Rust-based CLI and spawned reporter using tracing env-filter syntax.

export SIMPCAT_LOG_FILTER=debug

Used by: Rust-based CLI commands and the spawned reporter
Set before: simpcat ... or python train.py
Default: each command uses its built-in default when unset, typically info
Reporter logs are written to <run-dir>/logs/debug.log

`SIMPCAT_DEBUG`

Enable noisy Python SDK socket-send diagnostics.

export SIMPCAT_DEBUG=1

Used by: Python SDK hot path
Effect: emits a warning for each SDK-to-reporter socket send with payload size and elapsed time
Default: unset