User settings are optional deployment preferences for one workstation. They are not Run configuration, are not compiled into an ExecutionPlan, and are not written into a lock file.

Default behavior

The canonical default is no user settings file. Reading settings never creates one. With no file and no FASTSIM_* environment override, FastSim behaves exactly as it did before this feature:

  • Run authoring and project configuration remain the only simulation inputs;
  • CLI-owned outputs use ./outputs only when an enabled plugin requests run.output;
  • project cache, Registry, network, GPU and presentation defaults are unchanged.

FastSim creates the file only after an explicit settings set or settings import. Removing the final stored key removes the file again.

Location and precedence

The default paths are:

Platform Path
Linux $XDG_CONFIG_HOME/fastsim/config.toml, otherwise ~/.config/fastsim/config.toml
macOS ~/Library/Application Support/FastSim/config.toml
Windows %APPDATA%\FastSim\config.toml

FASTSIM_SETTINGS_FILE selects a different file for managed deployments and tests. fastsim settings --file PATH ... selects a file for one settings command.

Effective values use this precedence:

  1. an explicit command-line option;
  2. its documented environment variable;
  3. the persisted user setting;
  4. the pre-existing FastSim default.

Project fields still take precedence over user fallback values. For example, a project cache_dir is not replaced by paths.cache_root.

Supported keys

Key Environment Consumer
outputs.root FASTSIM_OUTPUT_ROOT fastsim run and fastsim outputs
paths.cache_root FASTSIM_CACHE_ROOT project resource cache fallback
paths.temp_root FASTSIM_TEMP_ROOT temporary files created by CLI processes
registries.sources FASTSIM_REGISTRIES additional local or pinned HTTPS Registry indexes
network.offline FASTSIM_OFFLINE resource resolver network policy
network.timeout_s FASTSIM_NETWORK_TIMEOUT_S resource download timeout
cli.language FASTSIM_LANGUAGE operator-facing language preference
cli.color FASTSIM_COLOR auto, always, or never color policy
cli.output_format FASTSIM_OUTPUT_FORMAT rich, plain, or json CLI output
cli.log_level FASTSIM_LOG_LEVEL CLI logging level
compute.gpu_ids FASTSIM_GPU_IDS default CUDA_VISIBLE_DEVICES for fastsim run
compute.max_workers FASTSIM_MAX_WORKERS bounded explicit jobs such as output verification and Viewer preparation
server.default_url FASTSIM_SERVER_URL fastsim server status
viewer.cache_root FASTSIM_VIEWER_CACHE_ROOT fastsim outputs open prepared-frame cache
viewer.cache_limit_gb FASTSIM_VIEWER_CACHE_LIMIT_GB Viewer cache size limit
credentials.registry_token_env — name of an environment variable holding a Registry bearer token

The file never stores a bearer token. Authorization is attached only to configured HTTPS Registry origins and is stripped if a redirect changes origin.

Local Registry values become absolute paths. A remote value must be immutable and pinned:

bash
fastsim settings set registries.sources \
  'https://registry.example/index.yaml#sha256=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef'
fastsim settings set credentials.registry_token_env FASTSIM_PRIVATE_REGISTRY_TOKEN

For more than one environment-provided Registry, set FASTSIM_REGISTRIES to a JSON array of strings. A single pinned HTTPS URL is accepted directly.

Simulation semantics such as backend, physics rate, seed, entities, cameras, plugins, recording streams and codecs do not belong here. Keep them in the Run, Scenario, component or plugin configuration so a lock remains reproducible.

Commands

bash
fastsim settings path
fastsim settings list
fastsim settings list --effective
fastsim settings get outputs.root
fastsim settings describe
fastsim settings describe compute.gpu_ids
fastsim settings set outputs.root /data/fastsim/outputs
fastsim settings unset outputs.root
fastsim settings validate
fastsim settings export --to yaml --output fastsim-settings.yaml
fastsim settings import fastsim-settings.yaml
fastsim settings import fastsim-settings.yaml --replace
fastsim settings reset --yes

All commands accept --json after the subcommand. path, list, get, describe, validate, and export are read-only. reset and output deletion commands require --yes; FastSim does not hide a destructive confirmation in an interactive prompt.

Writes use a same-directory temporary file, fsync, atomic replacement and mode 0600. FastSim gives a newly created settings directory mode 0700 but never changes the permissions of an existing parent directory.