Skip to content

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.78.0 (one new public SOUP_* name, SOUP_LOOP_FEEDBACK_LOG, and one internal one, SOUP_LOOP_DETACHED; new in v0.78.0: CUBLAS_WORKSPACE_CONFIG read by the VRAM pre-flight of a streamed run, a warning when a cache-folder variable is ignored, the .checkpoint_now file working, the scope of SOUP_TOOL_AUTH_TOKEN widened by two routes, and new state files (the loop's logs, the soup eval retention ledger and the soup docs search index), listed in their tables; 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 soup invocation appends one line to ~/.soup/audit.jsonl, soup --help included, unless audit logging is off. Running the CLI once is enough to create ~/.soup/. To keep a scratch session out of your real home, set SOUP_NO_AUDIT_LOG=1 and point HOME (USERPROFILE on Windows) at a disposable directory.

Switches

VariableAccepted valuesEffect
SOUP_NO_AUDIT_LOG1, true, yes or on, in any caseSame as --no-audit-log: no line is appended to the audit log. Any other value, 0 included, leaves it on.
SOUP_TELEMETRY1, true, yes or on, in any caseOpts 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_ENDPOINTA key of at most 256 characters with no control characters, and an HTTPS URL that passes the SSRF policyPoint 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. SOUP_AUDIT_LOG_PATH says so, with a one-line warning on stderr (falling back to default), and since v0.78.0 so do the two cache-folder variables at the end of the table; for the rest, check where the file actually appeared. Most of them also ignore a value that contains control characters (SOUP_BATCH_CACHE_PATH does not check, and SOUP_ADVISE_HISTORY_PATH rejects only a NUL byte).
  • Uncontained overrides. SOUP_DB_PATH, SOUP_REGISTRY_DB_PATH, SOUP_DRAFT_REGISTRY_PATH and, since v0.76.0, SOUP_PLUGIN_STATE_PATH are used exactly as given, with no containment check. That makes thirteen variables that move one file or directory: nine contained and four uncontained.
VariableMovesDefaultKind
SOUP_DB_PATHThe experiments database: every tracked run, soup runs, the eval leaderboard~/.soup/experiments.dbUncontained
SOUP_REGISTRY_DB_PATHThe model registry database~/.soup/registry.dbUncontained
SOUP_DRAFT_REGISTRY_PATHThe registry of distilled speculative-decoding drafts~/.soup/drafts.jsonUncontained
SOUP_PLUGIN_STATE_PATHThe plugin opt-in state that soup plugins enable and disable write~/.soup/plugins.jsonUncontained, ~ expanded, at most 4096 characters and no NUL byte (new in v0.76.0)
SOUP_AUDIT_LOG_PATHThe audit log~/.soup/audit.jsonlContained, and at most 4096 characters
SOUP_BATCH_CACHE_PATHThe cache of the batch size the OOM probe picked~/.soup/batch_cache.jsonContained
SOUP_ADVISE_HISTORY_PATHThe soup advise verdict history~/.soup/advise_history.jsonlContained
SOUP_DEPLOY_AUTOPILOT_CACHEThe soup deploy autopilot --measure cache~/.soup/deploy_autopilot_cache.jsonContained
SOUP_EDIT_GOVERNOR_DBThe edit-governor store~/.soup/edit_governor.dbContained, and at most 4096 characters
SOUP_NAMESPACE_PIN_DBThe namespace-pin store~/.soup/namespace_pin.dbContained, and at most 4096 characters
SOUP_BRANCHES_DIRThe adapter-branch pointer directory, created if missing~/.soup/branches/Contained
SOUP_LAYER_STREAM_CACHE_DIRThe layer-streaming shard cache root~/.soup/layer-stream/Contained, ~ expanded; since v0.78.0 a value that is ignored is logged once (see below)
SOUP_SPECTRUM_CACHE_DIRThe Spectrum scan cache root, which also holds the weights copy described below~/.soup/spectrum/Contained, ~ expanded; since v0.78.0 a value that is ignored is logged once (see below)

Since v0.78.0 (#2620) these two cache variables no longer fall back in silence. A value outside your home directory, the working directory and the temporary directory, or one that contains a control character, is still ignored and the cache goes to ~/.soup/layer-stream or ~/.soup/spectrum, but Soup now logs one warning per process naming the variable, the rejected value, the reason and the folder it uses instead (the text for the first case, run: SOUP_LAYER_STREAM_CACHE_DIR='C:/ProgramData/soupcache' is ignored: it is outside $HOME, the working directory and the temp directory. Using <home>\.soup\layer-stream instead. To use that folder, run soup from a working directory on the same drive, or put the folder under $HOME.). It is a log line on stderr, not a console panel, and soup doctor --disk does not read the layer-stream root, so it prints no warning. Through v0.77.2 the cache went to ~/.soup without a word. To keep a cache on another drive, run soup from a working directory on that drive, or place the folder under your home directory.

Variables Soup uses between its own processes

None of these is meant to be set by hand.

VariableSet by and read byWhat it does
SOUP_MCP_RUN_IDSet by soup mcp serve --allow-execute on the training process it launches; read by soup trainsoup train adopts it as its run id, so the experiments row and the MCP launch record describe the same run.
SOUP_CANDIDATE_RUN_IDRead by the pre-push hook that soup eval gate-install writes; you export itThe 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.
SOUP_LOOP_DETACHEDSet to 1 by soup loop watch --detach in the environment of the child it starts; read by soup loop watch (new in v0.78.0)Only a child that carries it removes the PID file when it exits. A plain foreground watch never touches that file.

Behaviour hints

VariableAccepted valuesEffect
SOUP_BENCH_BACKENDtransformers, vllm, sglang or mlx, in any casesoup bench with --backend auto (the default) takes this before it inspects the model directory. An unrecognised value is ignored.
SOUP_LOOP_TRACE_DIRA directoryWith --pre-wired, where soup loop harvests serve logs from. Since v0.78.0 (#2507) the order is this variable, then the trace_dir saved in loop.yaml (by soup loop init --trace-dir or soup loop set trace_dir), then .soup-loops/traces; the served model's directory is no longer read, so a dataset next to the weights is not harvested as serve logs. soup loop init and soup loop status print which of the three applies. The setting is deliberately not held to the working directory (soup loop set trace_dir accepted a directory outside it in a run, and only warned when it did not exist yet). See soup loop.
SOUP_LOOP_FEEDBACK_LOGA pathNew in v0.78.0. With --pre-wired, the file soup serve --feedback-log writes and the loop reads: it overrides the feedback_log saved in loop.yaml (by soup loop init --feedback-log), and the default is .soup-loops/feedback.jsonl. The loop's read side has no working-directory check (a configured file that does not exist yet gives a warning, not an error; a directory in its place is refused), while the write side, soup serve --feedback-log, must stay under the working directory. See soup loop.
SOUP_LOOP_SERVE_ENDPOINTAn http or https URLWith --pre-wired, the server soup loop deploys a canary adapter on. Since v0.78.0 (#2518) the deploy stage asks that server to load the adapter (POST /v1/adapters/load), which needs soup serve --adapter-dir <dir> and a token on the server, and the loop sends the token from SOUP_TOOL_AUTH_TOKEN; the canary then takes the share of keyed traffic that --canary-traffic sets. soup loop status asks the same server's /health which adapter is active. 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_DBA path under the working directory, not a symlinkNew 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_DIRSExtra folders on other NVMe drives, separated by ; on Windows and : elsewhereNew 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.
CUBLAS_WORKSPACE_CONFIGPyTorch's own SIZE:COUNT list, sizes in KiB (for example :4096:8); :0:0 turns the workspace offNew in v0.78.0 (#2749). Read by the VRAM pre-flight of a layer-streamed soup train on a CUDA card, which now prices two allocator-visible cuBLAS workspaces: 8,320 KiB each below compute capability 9, 32 MiB each on capability 9 or above, or, when this variable is set, the sum of its pairs for each, and 64 MiB in total when the capability cannot be read (upstream's constants). Soup does not set it. cuBLAS buffers outside PyTorch's allocator are not in that estimate. See Layer streaming.
PATHEXTWindows onlyRead 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_OFFLINE1, true, yes or on, in any caseRead 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_KEYThe path to an ed25519 private key in PEM formThe 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.

VariableRead byNotes
HF_TOKEN, HUGGINGFACE_HUB_TOKENEvery Hugging Face operation: soup push, soup data push, soup deploy hf-space, downloads through Soup's hub wrapperOrder: 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_ENDPOINTThe same operationsAn 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 modelersThe same validation as HF_ENDPOINT.
MODELSCOPE_API_TOKEN, MODELERS_TOKENUploads to those two hubsEach hub reads only its own credential and neither falls back to HF_TOKEN (since v0.75.1).
OPENAI_API_KEYsoup data generate --provider openai; the judge client of soup eval judgeThe 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_KEYThe Anthropic data provider and the Anthropic judge of the data-forge commandsEnvironment only.
LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEYsoup ingest --source langfuse --pullBoth 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_HOSTThe same pullThe 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_TOKENsoup ship --push and soup adapters pr --pushThe 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_KEYsoup train --cloud lambda --cloud-submitAll three are required. LAMBDA_REGION is optional and defaults to us-tx-1. See Backends.
MODAL_TOKEN_ID, MODAL_TOKEN_SECRETsoup train --cloud modal --cloud-submitBoth set, or a ~/.modal.toml, or a prior modal setup.
RUNPOD_API_KEY, RUNPOD_SSH_PRIVATE_KEYsoup 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). Since v0.78.0 it uses RunPod's REST API v2 (upstream says RunPod announced the retirement of REST API v1 for 2026-11-15, #2877), which rests on the published API reference and not on a real account. 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, and since v0.78.0 soup train --cloud refuses a config that names a local input file at plan time (exit 2). See Backends.
SOUP_TOOL_AUTH_TOKENsoup 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, feedback and adapter routes (generation, /v1/models, /health and /metrics still carry no token), and /v1/tools/python and /v1/tools/bash (since v0.77.0) and POST /v1/adapters/load (since v0.78.0) answer 401 without it on every bind, loopback included; POST /v1/feedback takes one only when the server has one, and always on a non-loopback bind (see Serving). soup loop watch sends it when its deploy stage loads and activates an adapter and on its paraphrase call, soup loop rollback sends it when it tells the server, and watch 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_PATHGGUF exportResolution 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_THREADSsoup llamaPassed 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_KEYsoup eval aiderWhichever 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_HOMEsoup env lockEither 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-streamed soup train on 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, and soup train had already initialised it when it detected the device, so in upstream's words every streamed CUDA run printed expandable_segments allocator hint not enabled: CUDA was already initialised before Soup could set it.
  • HF_DEACTIVATE_ASYNC_LOAD=1, since v0.77.0, by soup train, soup sweep and soup bench train when the run's device is Apple Silicon MPS (the transformers backend on a Mac, not backend: mlx), with setdefault semantics, 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 doctor shows the value in its MPS panel.
  • NCCL_P2P_DISABLE=0 and NCCL_IB_DISABLE, plus NCCL_NVLS_ENABLE=1 on NVLink, with setdefault so your own values win. NCCL_IB_DISABLE is 1 on a single node and 0 when --nodes is above 1, so a multi-node launch leaves InfiniBand allowed; set NCCL_IB_DISABLE=1 yourself on every node of a TCP-only cluster (the command says so when --nodes is above 1). They are applied only by a soup train --gpus N process that is already inside a launcher (for example one you started yourself with accelerate launch and --gpus N still on the command line); the ranks that soup train --gpus N launches for you do not receive --gpus and 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 custom reward_fn included). A value you set is kept, and upstream states that any non-empty value, 0 included, 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 on PATH as an absolute path. soup llama hands its child the value 1 whatever 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 relative PATH entry, which Soup now skips.
  • PYTHONIOENCODING=utf-8, on Windows at startup, so child processes inherit UTF-8 output.
  • MASTER_ADDR=localhost and MASTER_PORT=29500, by soup doctor --nccl for 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.78.0 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/

PathCreated byNotes
experiments.dbEvery 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 emptySOUP_DB_PATH moves it. Since v0.78.0 the first v0.78.0 soup that opens a v0.77.2 database adds nullable columns to it in place (in a run, runs went from 26 to 29 columns and metrics from 12 to 15), and loss, lr and speed may be NULL where v0.77.2 stored 0.0; a script that reads the file directly and treats 0.0 as unmeasured should treat NULL the same way. A database written by v0.78.0 stays readable by v0.77.2: in a run, v0.77.2's soup runs and soup runs show printed such a database normally. See Experiment tracking.
registry.dbAny command that opens the registry: soup registry, --attach-to-registry, soup card, soup can packSOUP_REGISTRY_DB_PATH moves it. Mode 0600 on POSIX. See Model registry.
audit.jsonlEvery invocationPast 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.jsonlsoup advise run --recordSOUP_ADVISE_HISTORY_PATH moves it.
advise_last.jsonsoup advise runScratch for soup advise explain. No override.
datasets.jsonsoup data registerThe registry that soup data registry lists. No override.
batch_cache.jsonAn SFT run that uses the OOM-probe batch sizeSOUP_BATCH_CACHE_PATH moves it.
deploy_autopilot_cache.jsonsoup deploy autopilot --measureSOUP_DEPLOY_AUTOPILOT_CACHE moves it.
drafts.jsonsoup draft distillCreated 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.dbsoup edit set, unless --no-governorSOUP_EDIT_GOVERNOR_DB moves it.
namespace_pin.dbA Hugging Face download through Soup's hub wrapperSOUP_NAMESPACE_PIN_DB moves it. See Supply chain security.
branches/soup adapters branchOne <name>.json pointer per branch. SOUP_BRANCHES_DIR moves it.
telemetry_idThe first opted-in telemetry eventA 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.cppA clone of the pinned tag (b12423 since v0.78.0; b5270 before). Skipped when --llama-cpp or LLAMA_CPP_PATH supplies one. An existing checkout is reused as it is, so after an upgrade delete ~/.soup/llama.cpp to have the next export clone the new tag.
plugins.jsonsoup plugins enable and disableNew 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 runOne 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. Since v0.78.0 the disk pre-flight lists the other <model>@<commit> slots of the same base with their sizes and paths and names soup prune-layer-cache, which removes stale ones (a dry run unless --yes, and it never deletes a stripe folder). See Layer streaming and Streaming disk tier.
spectrum/<model>.jsonsoup spectrum scanThe 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 modelA 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-downloadNo override.
cache/docs/docs_index.jsonsoup docs search (new in v0.78.0)The BM25 index over the documentation bundled in the installed package, built on the first search and read back while the bundled text is unchanged. A failed write does not break the search. No override.

Files in the working directory

PathCreated byNotes
.soup/loop.yaml and .soup-loops/soup loopThe loop's state file (written atomically, at most 1 MiB), and below .soup-loops/ its pairs/, adapters/<run>/ with <run>.train.log, verdicts/ (<run>.ship.log, <run>.json, <run>.corrections.jsonl and <run>.held-out.jsonl), traces/ and one <iteration-id>/iteration.json per iteration. Since v0.78.0 it also keeps append-only JSONL logs there: iterations.jsonl, versions.jsonl, progress.jsonl, paraphrases.jsonl, holdout.jsonl and, written by soup serve --feedback-log and only read by the loop, feedback.jsonl; upstream's docs/loop-formats.md defines five of them (feedback, paraphrases, iterations, versions and progress; it also defines the conversation log under traces/) and none for holdout.jsonl, and the package ships their JSON Schemas. Logs are created owner-only (0600) on POSIX, and a link, junction or hard link in the way is refused. The loop's own files are held to the working directory; the trace directory and the feedback log it reads are the exceptions the two variables above describe.
.soup/loop.pid and .soup/loop.logsoup loop watch --detachThe PID file (JSON: pid, started_at, log) and the log of the detached watcher, rotated to loop.log.1 at 10 MiB. Only a detached child removes the PID file when it exits.
.soup/canary-stats.jsonThe canary bookkeeping of the soup serve app, read by soup loopCanary 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-executeA <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>.crashA soup train run that fails with an exceptionWritten 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 credentials redacted before the file is written: since v0.78.0 (#2883) URL user names and passwords, sensitive query parameters, common API-token shapes, Authorization and Bearer headers, JWTs, private-key blocks and values under credential-named keys become <redacted>, and the bundle records counts only. Upstream calls the redaction pattern-based and best-effort, so read a bundle 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 modelersHugging Face downloads do not use it. Must stay under the working directory.
soup-env.locksoup env lockThe default name; --output changes it.
soup.tfstatesoup plan and soup applyThe default name; --state changes it.
.soup-signature.jsonsoup adapters signInside the adapter directory.
retention.jsonsoup eval retention (new in v0.78.0)The default ledger of control tasks and the scores each recorded version got on them, created by --add-task together with --record (without --record a run is a dry run that writes nothing); --ledger changes the name, and it must stay under the working directory (exit 3 otherwise). See soup ship.
soup_run.jsonsoup 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.pysoup 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_nowYou, by touching it in the output directory of a run that is going (an output directory that resolves outside the working directory is never polled: read from utils/checkpoint_trigger.py)Since v0.78.0 (#2414) a Hugging Face Trainer run reads it at each optimizer-step boundary, saves a checkpoint and keeps training, and removes the file only after the checkpoint succeeded (a failed save leaves it for a retry; a symlink or a file that is not a regular file is neither followed nor consumed). Native MLX training and loops that do not use the Hugging Face Trainer, task: unlearn included, do not read it; through v0.77.2 no code in soup train polled it and touching it did nothing. See Observability.
grace_codebook.jsonsoup edit set --method graceA sidecar in the edit's output directory.
.soup_build_state.sqlitesoup buildUnder the build's output directory.

Soup also creates short-lived temporaries in the directory it is working in, named .soup_merge_tmp_<name>_<random suffix>, .soup_mlx_merge_*, .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 merge 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). Since v0.78.0 (#2299) every adapter export creates a fresh, uniquely named directory, .soup_merge_tmp_<adapter>_<random suffix>, and removes only that one, so a .soup_merge_tmp_<adapter>* directory left by an earlier run is never reused and never deleted. Through v0.77.2 the name was fixed, .soup_merge_tmp_<adapter>/, and one that was already there was left alone with the output Leaving <path>: it existed before this export., a message that v0.78.0 no longer prints. .soup_mlx_merge_* is the staging directory that soup merge --backend mlx makes next to its output folder, in the output's parent directory (new in v0.78.0).

See also

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.