Environment variables and state files
Soup reads a short list of environment variables and writes a handful of files outside the output directory of a run. This page lists them as of v0.77.2 (the set of SOUP_* names is the one v0.77.1 had; new in v0.77.2: the format soup serve requires of the value of SOUP_TOOL_AUTH_TOKEN, and soup doctor reading CUDA_VISIBLE_DEVICES; new in v0.77.1: NoDefaultCurrentDirectoryInExePath among the variables Soup sets, and the way PATH and PATHEXT are read for every external program; new in v0.77.0: SOUP_TOOL_AUTH_TOKEN, SOUP_LOOP_THUMBS_DB, RUNPOD_API_KEY and RUNPOD_SSH_PRIVATE_KEY, HF_HUB_OFFLINE (read by soup train for the run record), and HF_DEACTIVATE_ASYNC_LOAD among the variables Soup sets), with which path overrides are containment-checked and which are used exactly as given, and the command that creates each file. ~ is your home directory (%USERPROFILE% on Windows).
Every
soupinvocation appends one line to~/.soup/audit.jsonl,soup --helpincluded, unless audit logging is off. Running the CLI once is enough to create~/.soup/. To keep a scratch session out of your real home, setSOUP_NO_AUDIT_LOG=1and pointHOME(USERPROFILEon Windows) at a disposable directory.
Switches
| Variable | Accepted values | Effect |
|---|---|---|
SOUP_NO_AUDIT_LOG | 1, true, yes or on, in any case | Same as --no-audit-log: no line is appended to the audit log. Any other value, 0 included, leaves it on. |
SOUP_TELEMETRY | 1, true, yes or on, in any case | Opts in to telemetry, which is off by default. --no-telemetry is a root option and goes before the subcommand; it overrides this variable. As shipped, the bundled project key is a placeholder and nothing is sent even when you opt in. See Tracker and eval pro. |
SOUP_POSTHOG_KEY and SOUP_POSTHOG_ENDPOINT | A key of at most 256 characters with no control characters, and an HTTPS URL that passes the SSRF policy | Point telemetry at your own PostHog project. The key is what matters: with the bundled placeholder key an opted-in command prints Notice: telemetry is not yet live. and sends nothing, and an endpoint without a key of your own sends nothing either. The endpoint is optional; without it the bundled PostHog endpoint is used. When set it must be HTTPS and pass the SSRF policy, and upstream's SECURITY.md adds that a loopback, private or internal host is refused. Only with a key of your own does an opted-in command make one HTTPS POST at exit, upstream says. Only consulted when telemetry is opted in. |
Paths you can move
Each override below replaces one file or directory under ~/.soup/. They come in two kinds, and the difference matters when you mistype one.
- Contained overrides. The path is resolved, symlinks followed, and must sit under your home directory, the current working directory or the system temporary directory. Anything else is ignored and the default is used, with no error, so a path outside those three roots simply has no effect. Only
SOUP_AUDIT_LOG_PATHsays so, with a one-line warning on stderr (falling back to default); for the rest, check where the file actually appeared. Most of them also ignore a value that contains control characters (SOUP_BATCH_CACHE_PATHdoes not check, andSOUP_ADVISE_HISTORY_PATHrejects only a NUL byte). - Uncontained overrides.
SOUP_DB_PATH,SOUP_REGISTRY_DB_PATH,SOUP_DRAFT_REGISTRY_PATHand, since v0.76.0,SOUP_PLUGIN_STATE_PATHare used exactly as given, with no containment check. That makes thirteen variables that move one file or directory: nine contained and four uncontained.
| Variable | Moves | Default | Kind |
|---|---|---|---|
SOUP_DB_PATH | The experiments database: every tracked run, soup runs, the eval leaderboard | ~/.soup/experiments.db | Uncontained |
SOUP_REGISTRY_DB_PATH | The model registry database | ~/.soup/registry.db | Uncontained |
SOUP_DRAFT_REGISTRY_PATH | The registry of distilled speculative-decoding drafts | ~/.soup/drafts.json | Uncontained |
SOUP_PLUGIN_STATE_PATH | The plugin opt-in state that soup plugins enable and disable write | ~/.soup/plugins.json | Uncontained, ~ expanded, at most 4096 characters and no NUL byte (new in v0.76.0) |
SOUP_AUDIT_LOG_PATH | The audit log | ~/.soup/audit.jsonl | Contained, and at most 4096 characters |
SOUP_BATCH_CACHE_PATH | The cache of the batch size the OOM probe picked | ~/.soup/batch_cache.json | Contained |
SOUP_ADVISE_HISTORY_PATH | The soup advise verdict history | ~/.soup/advise_history.jsonl | Contained |
SOUP_DEPLOY_AUTOPILOT_CACHE | The soup deploy autopilot --measure cache | ~/.soup/deploy_autopilot_cache.json | Contained |
SOUP_EDIT_GOVERNOR_DB | The edit-governor store | ~/.soup/edit_governor.db | Contained, and at most 4096 characters |
SOUP_NAMESPACE_PIN_DB | The namespace-pin store | ~/.soup/namespace_pin.db | Contained, and at most 4096 characters |
SOUP_BRANCHES_DIR | The adapter-branch pointer directory, created if missing | ~/.soup/branches/ | Contained |
SOUP_LAYER_STREAM_CACHE_DIR | The layer-streaming shard cache root | ~/.soup/layer-stream/ | Contained, ~ expanded |
SOUP_SPECTRUM_CACHE_DIR | The Spectrum scan cache root, which also holds the weights copy described below | ~/.soup/spectrum/ | Contained, ~ expanded |
Variables Soup uses between its own processes
Neither of these is meant to be set by hand.
| Variable | Set by and read by | What it does |
|---|---|---|
SOUP_MCP_RUN_ID | Set by soup mcp serve --allow-execute on the training process it launches; read by soup train | soup train adopts it as its run id, so the experiments row and the MCP launch record describe the same run. |
SOUP_CANDIDATE_RUN_ID | Read by the pre-push hook that soup eval gate-install writes; you export it | The run the hook compares against the baseline. Unset, the hook prints SOUP_CANDIDATE_RUN_ID not set; skipping regression gate. and exits 0, so the push goes through ungated. See soup eval design. |
Behaviour hints
| Variable | Accepted values | Effect |
|---|---|---|
SOUP_BENCH_BACKEND | transformers, vllm, sglang or mlx, in any case | soup bench with --backend auto (the default) takes this before it inspects the model directory. An unrecognised value is ignored. |
SOUP_LOOP_TRACE_DIR | A directory | With --pre-wired, where soup loop harvests serve logs from. When unset it uses the served model's directory if that is a local directory, then .soup-loops/traces. It is deliberately not held to the working directory. See soup loop. |
SOUP_LOOP_SERVE_ENDPOINT | An http or https URL | With --pre-wired, the server soup loop activates a canary adapter on. Unset, nothing is deployed and the iteration says so. The host must be a loopback name, or a loopback, private or link-local IP literal; plain http is accepted only for loopback, so a private or link-local address needs https. A public host, or any hostname that is not a loopback name, is refused because Soup does not resolve DNS. |
SOUP_LOOP_THUMBS_DB | A path under the working directory, not a symlink | New in v0.77.0. With --pre-wired, the database soup serve --record-thumbs writes, which the soup loop harvest turns into preference pairs; it overrides the --thumbs-db that soup loop init recorded. soup loop watch checks it before it starts or detaches and exits 2 when it is refused. See soup loop. |
SOUP_LAYER_STREAM_STRIPE_DIRS | Extra folders on other NVMe drives, separated by ; on Windows and : elsewhere | New in v0.76.0. Stripes the layer-streaming shard cache across the primary root and these folders; read by soup train and soup train --dry-run when stream_layers: true, and listed by soup doctor. Unlike the path overrides above, a bad entry is not ignored: it refuses the run, naming the entry and the rule. Every entry must be an absolute path to a folder that already exists, not a symlink or directory junction, on its own volume (different from the primary root and from every other entry), and classify as NVMe (training.stream_disk_kind overrides a wrong probe); at most 6 folders. Soup creates only its own folder inside each root, owner-only (mode 0700 on POSIX, a protected ACL for your account and SYSTEM on Windows), and never deletes an existing layer file, index or folder inside a stripe folder (it removes only the temporary .soup.*.tmp file of a write that failed). Changing the list re-shards the cache. See Streaming disk tier. |
PATHEXT | Windows only | Read whenever Soup looks for an external program on PATH, since v0.77.1 for every program it starts by name and not only for the accelerate launcher of soup train --gpus N, so accelerate finds accelerate.exe. Unset, empty or naming no extension, it falls back to .COM;.EXE;.BAT;.CMD. Only absolute PATH directories are searched: not the current directory, and not an empty or relative entry such as . or bin (on Windows also \bin or C:bin). A tool that is only in the current directory or in a relative entry is no longer found: put its directory on PATH as an absolute path, or give the tool's path (#2205). |
HF_HUB_OFFLINE, TRANSFORMERS_OFFLINE | 1, true, yes or on, in any case | Read by soup train for this since v0.77.0. Either one skips the single Hub lookup, with a 5-second timeout, that records the base model's commit for soup_run.json; the revision is then left unrecorded and its source is recorded as offline. Since v0.77.1 either one also stops soup plan, the VRAM pre-flight of soup train and soup profile from fetching a Hub model's config.json (and the Hub's safetensors headers) over the network to size a run; a config.json already in the Hugging Face cache is still read. soup apply never reads the model (see Pre-flight and tooling). Since v0.77.2 soup profile --model with either one set reads a local directory or a cached config.json and otherwise exits 1 saying that the file is not in the cache and the variable is set, and soup merge, which loads the base at the Hub commit recorded in the adapter's training provenance, fails when that commit is not cached where v0.77.1 merged whatever was cached (#2285, #2485; the merge was not exercised by hand before the release). |
SOUP_SIGNING_KEY | The path to an ed25519 private key in PEM form | The key for soup adapters sign --backend ed25519 and soup attest emit --sign ed25519 when --key is not given. It is a path, not the key text. |
Credentials and endpoints Soup reads
Soup reads these and stores none of them. The audit log masks the value of an option whose name contains token, key, secret, password, passwd or credential (apart from a fixed list of names that never carry one, such as --max-tokens, --min-tokens and --tokenizer), and, since v0.76.1, the values of --slack-url and --discord-url. Through v0.76.0 a webhook URL was recorded as typed. Since v0.77.0, lines written by older versions get the same masking as new lines, applied once when the log is next written (#2065, see Governance). soup llama and the gh call behind --push are started with a filtered environment, as the table notes.
| Variable | Read by | Notes |
|---|---|---|
HF_TOKEN, HUGGINGFACE_HUB_TOKEN | Every Hugging Face operation: soup push, soup data push, soup deploy hf-space, downloads through Soup's hub wrapper | Order: an explicit token, HF_TOKEN, HUGGINGFACE_HUB_TOKEN, then the cached login at ~/.cache/huggingface/token and the legacy ~/.huggingface/token. See Hugging Face Hub integration. |
HF_ENDPOINT | The same operations | An alternative Hub endpoint. HTTPS for a remote host, plain HTTP only for loopback; 0.0.0.0 and any scheme other than http or https are refused. |
MODELSCOPE_ENDPOINT, MODELERS_ENDPOINT | --hub modelscope and --hub modelers | The same validation as HF_ENDPOINT. |
MODELSCOPE_API_TOKEN, MODELERS_TOKEN | Uploads to those two hubs | Each hub reads only its own credential and neither falls back to HF_TOKEN (since v0.75.1). |
OPENAI_API_KEY | soup data generate --provider openai; the judge client of soup eval judge | The judge client uses it only for the openai provider and never for server or ollama. With --provider openai --api-base <url> it is sent to the URL you name. In an eval-gate suite, an https judge gets it only when its host is exactly api.openai.com. |
ANTHROPIC_API_KEY | The Anthropic data provider and the Anthropic judge of the data-forge commands | Environment only. |
LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY | soup ingest --source langfuse --pull | Both required, environment only, never a flag, so they never reach the audit log. The other soup ingest sources do not fetch anything; for them the credential variable only changes a console note. See Trace ecosystem. |
LANGFUSE_BASE_URL, LANGFUSE_HOST | The same pull | The first one set wins, in that order. Default https://cloud.langfuse.com. It must be https://, and a private or loopback address also needs --allow-private-host. |
GITHUB_TOKEN, GH_TOKEN | soup ship --push and soup adapters pr --push | The first non-blank one, in that order, posts the PR comment through the gh program, which gets a filtered environment. |
LAMBDA_API_KEY, LAMBDA_SSH_KEY_NAME, LAMBDA_SSH_PRIVATE_KEY | soup train --cloud lambda --cloud-submit | All three are required. LAMBDA_REGION is optional and defaults to us-tx-1. See Backends. |
MODAL_TOKEN_ID, MODAL_TOKEN_SECRET | soup train --cloud modal --cloud-submit | Both set, or a ~/.modal.toml, or a prior modal setup. |
RUNPOD_API_KEY, RUNPOD_SSH_PRIVATE_KEY | soup train --cloud runpod --cloud-submit (new in v0.77.0) | Both required; without them the submit exits 1. The second is the path of a private key file, with its public key beside it as <path>.pub. The API key is not put in the environment of ssh and scp, and a config that contains its value is refused. The RunPod controller has not been run against a real RunPod account yet (tracked as #2098). It makes one attempt, copies the results once with a 15-minute limit into a new directory next to the output path and deletes the Pod afterwards; local input files are not uploaded, so the base and the data must be reachable from the Pod. See Backends. |
SOUP_TOOL_AUTH_TOKEN | soup serve --tool-auth-token and soup loop watch --tool-auth-token (new in v0.77.0) | The default for both options; a value on the command line wins, and the variable keeps the token out of the shell history. On soup serve it is the bearer token for the tool, thumbs and adapter routes, and since v0.77.0 /v1/tools/python and /v1/tools/bash answer 401 without it on every bind, loopback included (see Serving). soup loop watch sends it when its deploy stage activates an adapter, and hands it to a --detach child through the environment, not its argv. Since v0.77.2 (#2329) soup serve applies the token rule of soup ui and soup mcp serve to the value, from the option or from this variable: 16 to 128 characters from A-Z, a-z, 0-9, _ and -, the whole value (a trailing newline is refused). Any other value exits 2 before the model loads, on every bind, loopback included, and the message names the rule and never prints the value; v0.77.1 accepted any non-empty value. python -c "import secrets; print(secrets.token_urlsafe(32))" makes one. soup loop watch does not apply the rule itself: it sends the value as given, so it must be the one the server was started with. |
LLAMA_CPP_PATH | GGUF export | Resolution order: --llama-cpp, then this variable (ignored if the path does not exist), then ~/.soup/llama.cpp, then a fresh clone into ~/.soup/llama.cpp. |
LLAMA_CPP_HOME, GGML_CUDA, GGML_METAL, OMP_NUM_THREADS | soup llama | Passed through to the llama.cpp program, whose environment is otherwise filtered (on Windows names are matched without regard to case, and since v0.77.1 SYSTEMROOT, PATHEXT and NoDefaultCurrentDirectoryInExePath are kept as well). Soup finds that program in an absolute PATH directory and does not read LLAMA_CPP_HOME itself, although its not-found message suggests setting it. |
ANTHROPIC_API_KEY, AZURE_API_BASE, AZURE_API_KEY, AZURE_API_VERSION, GEMINI_API_KEY, OPENAI_API_BASE, OPENAI_API_KEY, OPENROUTER_API_KEY | soup eval aider | Whichever of these are set are forwarded into the Docker container as --env NAME, so the value is never on the command line. |
CUDA_VERSION, CUDA_HOME | soup env lock | Either supplies the CUDA version it records. CUDA_HOME is parsed for a version in the path (.../cuda-12.1, .../v12.1); a path with no version supplies nothing. Failing that it reads the version from torch, but only if torch is already imported. It does not query nvidia-smi. |
Soup's own code never reads WANDB_API_KEY or MLFLOW_TRACKING_URI; the tracker libraries do.
Variables Soup sets
PYTORCH_CUDA_ALLOC_CONF=expandable_segments:True, for a layer-streamedsoup trainon Linux (WSL2 included), set before CUDA starts since v0.77.0 (#2156). A value you exported is kept, and an empty one counts as unset. macOS and Windows are left alone; on Windows the allocator ignores the hint anyway, and Soup says so rather than claiming it took effect. Before v0.77.0 the hint was set only while CUDA was not yet initialised, andsoup trainhad already initialised it when it detected the device, so in upstream's words every streamed CUDA run printedexpandable_segments allocator hint not enabled: CUDA was already initialised before Soup could set it.HF_DEACTIVATE_ASYNC_LOAD=1, since v0.77.0, bysoup train,soup sweepandsoup bench trainwhen the run's device is Apple Silicon MPS (the transformers backend on a Mac, notbackend: mlx), withsetdefaultsemantics, so a value you exported wins. It switches off transformers' threaded weight loading, which upstream reports can crash with SIGABRT while the model loads on MPS (#2076).soup doctorshows the value in its MPS panel.NCCL_P2P_DISABLE=0andNCCL_IB_DISABLE, plusNCCL_NVLS_ENABLE=1on NVLink, withsetdefaultso your own values win.NCCL_IB_DISABLEis1on a single node and0when--nodesis above 1, so a multi-node launch leaves InfiniBand allowed; setNCCL_IB_DISABLE=1yourself on every node of a TCP-only cluster (the command says so when--nodesis above 1). They are applied only by asoup train --gpus Nprocess that is already inside a launcher (for example one you started yourself withaccelerate launchand--gpus Nstill on the command line); the ranks thatsoup train --gpus Nlaunches for you do not receive--gpusand so do not set them.NoDefaultCurrentDirectoryInExePath=1, on Windows at startup, since v0.77.1 (#2213), when it is not set: Windows then does not look in the current directory for a program started by bare name, whether by Soup or by a program it starts (eval scripts and the scripts behind a customreward_fnincluded). A value you set is kept, and upstream states that any non-empty value,0included, already leaves the current directory out, so no setting brings the old search back. To run a program from the current directory, give its path (./tool.exe, or an absolute path in quotes) or put its directory onPATHas an absolute path.soup llamahands its child the value1whatever the parent has, and the RunPod and Lambda controllers get it too. Elsewhere Soup does nothing: the current directory is searched there only through an empty or relativePATHentry, which Soup now skips.PYTHONIOENCODING=utf-8, on Windows at startup, so child processes inherit UTF-8 output.MASTER_ADDR=localhostandMASTER_PORT=29500, bysoup doctor --ncclfor the length of its bandwidth check; the previous values are restored afterwards.
Soup also reads, but does not set, the variables a launcher exports. RANK and WORLD_SIZE together, or any of ACCELERATE_MIXED_PRECISION, ACCELERATE_USE_DEEPSPEED and ACCELERATE_USE_FSDP, mark a process as an already-launched rank. RANK and LOCAL_RANK decide which process may write RL checkpoints. WORLD_SIZE is the first source for the world size a DeepSpeed config is resolved against, with the GPU count as the fallback, and LOCAL_WORLD_SIZE sets the ZeRO++ hierarchical-partition size when it divides that world size. Since v0.77.2 WORLD_SIZE inside an already-launched rank is also the process count that the VRAM pre-flight of soup train prices a sharded run against (outside a rank it uses --gpus times --nodes, or 1 without --gpus), and soup doctor reads CUDA_VISIBLE_DEVICES: when nvidia-smi lists a card that torch cannot use and the first entry hides every card nvidia-smi lists (a negative or out-of-range index, an empty value, or any other word that is not an index or a GPU- or MIG- UUID, which it does not check), it prints the setting as set and advises unsetting it, where it used to advise reinstalling PyTorch (#2206, #2313).
Variables that exist in the source and do nothing
API_HOST, API_PORT, API_KEY, GRADIO_HOST and GRADIO_PORT are parsed and validated by a helper (soup_cli.utils.ui_env.resolve_ui_env), but nothing in v0.77.2 calls that helper (a search of src/ finds no caller outside the module), so setting them changes nothing: on v0.75.2, soup ui --port 7899 with API_PORT, API_HOST and API_KEY all set still bound 127.0.0.1:7899 and printed a freshly generated token. An earlier upstream serving document listed them; the v0.76.0 one no longer does, and they are named here because older copies of it are still around. The Web UI is configured with soup ui --host, --port and --auth-token; see Web UI.
Files under ~/.soup/
| Path | Created by | Notes |
|---|---|---|
experiments.db | Every tracked run: soup train, soup sweep, and the soup eval commands that save results (benchmark and custom always, judge and aider only when given --run-id). Commands that only read it, such as soup runs, create it empty | SOUP_DB_PATH moves it. See Experiment tracking. |
registry.db | Any command that opens the registry: soup registry, --attach-to-registry, soup card, soup can pack | SOUP_REGISTRY_DB_PATH moves it. Mode 0600 on POSIX. See Model registry. |
audit.jsonl | Every invocation | Past 100 MiB the writer rotates it to audit.jsonl.1, keeping one backup. The writer refuses to follow a symbolic link or reparse point at its path on every platform (on Windows too, since v0.76.0). SOUP_AUDIT_LOG_PATH moves it; soup audit-log tail and soup audit-log rotate read and rotate it. Since v0.77.0 the pass that re-masks lines written by older versions leaves files beside it: audit.jsonl.masked-v1 once the pass is done, audit.jsonl.masked-v1.tried after a failed attempt (the next one waits a day), and, while a pass runs, a .audit-mask-*.tmp file that a later pass removes if an interrupted one left it. See Governance. |
advise_history.jsonl | soup advise run --record | SOUP_ADVISE_HISTORY_PATH moves it. |
advise_last.json | soup advise run | Scratch for soup advise explain. No override. |
datasets.json | soup data register | The registry that soup data registry lists. No override. |
batch_cache.json | An SFT run that uses the OOM-probe batch size | SOUP_BATCH_CACHE_PATH moves it. |
deploy_autopilot_cache.json | soup deploy autopilot --measure | SOUP_DEPLOY_AUTOPILOT_CACHE moves it. |
drafts.json | soup draft distill | Created on first registration; like the audit log, it refuses a symbolic link or reparse point at its path on Windows too since v0.76.0. SOUP_DRAFT_REGISTRY_PATH moves it. See soup draft. |
edit_governor.db | soup edit set, unless --no-governor | SOUP_EDIT_GOVERNOR_DB moves it. |
namespace_pin.db | A Hugging Face download through Soup's hub wrapper | SOUP_NAMESPACE_PIN_DB moves it. See Supply chain security. |
branches/ | soup adapters branch | One <name>.json pointer per branch. SOUP_BRANCHES_DIR moves it. |
telemetry_id | The first opted-in telemetry event | A random UUID, created even though, as shipped, nothing is sent. Delete it and a new one is generated on the next opt-in. |
llama.cpp/ | The first GGUF export that finds no llama.cpp | A clone. Skipped when --llama-cpp or LLAMA_CPP_PATH supplies one. |
plugins.json | soup plugins enable and disable | New in v0.76.0. A version-1 JSON file recording which plugins you opted in to: {"version": 1, "enabled": {"<name>": true}}. Written atomically, mode 0600 where the platform supports it, at most 64 KiB read back; a symlink at the path is refused, and an unreadable or malformed file is ignored with a warning. Anything that can write it can enable an installed plugin entry point. SOUP_PLUGIN_STATE_PATH moves it. See Plugin system. |
layer-stream/<model>/ | A layer-streaming run | One shard per decoder layer, keyed to the source weights. SOUP_LAYER_STREAM_CACHE_DIR moves the root; the pre-flight checks free space on the volume before it writes. With SOUP_LAYER_STREAM_STRIPE_DIRS set, the layers are spread over the primary root and a per-model folder inside each extra root. See Layer streaming. |
spectrum/<model>.json | soup spectrum scan | The scan result. --no-cache skips it. SOUP_SPECTRUM_CACHE_DIR moves the root. |
spectrum/weights/<model>/ | soup spectrum scan and layer streaming, for a Hugging Face model | A regular-file copy of the model's weights, made only when the Hub snapshot's files are symlinks that the sharder will not follow. It is as large as the weights; SOUP_SPECTRUM_CACHE_DIR moves it. |
sae-cache/<repo>/ | soup probe sae-diff --auto-download | No override. |
Files in the working directory
| Path | Created by | Notes |
|---|---|---|
.soup/loop.yaml and .soup-loops/ | soup loop | The loop's state file, and below .soup-loops/ its pairs/, adapters/, traces/ and one <iteration-id>/iteration.json per iteration. All held to the working directory. |
.soup/canary-stats.json | The canary bookkeeping of the soup serve app, read by soup loop | Canary outcome counters for the active rollout, flushed in batches (every 64 outcomes or two seconds). Held to the working directory and refused if it is a symlink; read back with a 64 KiB cap. |
.soup/mcp-runs/ | soup mcp serve --allow-execute | A <run_id>.log per executed run, and the config snapshot taken at plan time under <run_id>/. Relative to the server's working directory. |
.soup-crashes/crash_<UTC>_<hex>.crash | A soup train run that fails with an exception | Written once the failure is recorded. It holds the error trace, the run's config and metrics, GPU state and an environment summary that names fourteen non-secret variables (among them CUDA_VISIBLE_DEVICES, PYTORCH_CUDA_ALLOC_CONF, HF_ENDPOINT, HF_HOME, WORLD_SIZE and RANK), with token-shaped strings redacted. Read it before you attach it to a public issue. |
.soup_hub_cache/ | A model fetched from ModelScope or Modelers (training.hub in soup.yaml, or --hub on a command that takes one), and Modelers datasets from soup data download --hub modelers | Hugging Face downloads do not use it. Must stay under the working directory. |
soup-env.lock | soup env lock | The default name; --output changes it. |
soup.tfstate | soup plan and soup apply | The default name; --state changes it. |
.soup-signature.json | soup adapters sign | Inside the adapter directory. |
soup_run.json | soup train, in the output directory of a finished run (new in v0.77.0) | The run id, the base model id, the Hub revision recorded for it and how it was known, and the SHA-256 of the local training file taken at startup; each can be unknown. soup export reads it back. It is a provenance record, not a signed attestation. See Experiment tracking. |
soup_runpod_app.py | soup train --cloud runpod (new in v0.77.0) | The rendered RunPod controller stub, written under the working directory. Plan-only by default: writing it contacts nothing. |
.checkpoint_now | Nothing | Not a working trigger at v0.77.2: no code in soup train polls it, so touching it does nothing. See Observability. |
grace_codebook.json | soup edit set --method grace | A sidecar in the edit's output directory. |
.soup_build_state.sqlite | soup build | Under the build's output directory. |
Soup also creates short-lived temporaries in the directory it is working in, named .soup_merge_tmp_<name>, .soup_gguf_*, .soup.*.tmp and .soup-diskprobe-* (the last is the 64 MiB probe file of soup doctor --disk). They are scratch files, not state. Since v0.77.1 a failed soup export removes its .soup_merge_tmp_<adapter>/ directory (llama.cpp not found, a failed clone or dependency install, or a merge that dies while saving the model or tokenizer; the gguf, onnx, tensorrt, bitnet and gguf-ud paths) instead of leaving a multi-gigabyte directory next to the adapter (#1464, #2164). It removes only a directory the export created: one that was already there is left alone, and the output says Leaving <path>: it existed before this export.
See also
- Configuration, for what belongs in
soup.yamlrather than the environment. - CLI reference, including the root options
--no-audit-log,--no-telemetryand--log-level. - Supply chain security and Governance, for what the audit log, the pin store and the signing key are for.
Soup is free and Apache-2.0. If it saved you a training run, starring the repo costs nothing and helps most. You can also fund the GPU time behind the work a 4 GB laptop cannot reach.