Environment flags
yggdrasim_common/env_flags.py is the single source of truth for the
YGGDRASIM_* runtime flags: each one declares its name, category, summary,
accepted values, default, when a change takes effect, and where an override
is stored. Three surfaces read that one registry, and so does the table at
the bottom of this page:
On this page
- the launcher menu,
[E] Environment Flags (YGGDRASIM_*) - the Universal GUI, Environment -> Configuration (
/api/env_flags/list,/api/env_flags/{name}/set,/{name}/clear,/reset) yggdrasim_common.env_flagsitself, for anything that needs the contract in code
Which value wins
- The process environment.
VAR=... yggdrasim ..., a shellexport, or a CLI flag that sets the variable takes priority over everything else. - A persisted override, applied at process entry for flags the environment leaves unset.
- The flag's own default, which is what the Default column describes.
apply_persisted_env_overrides() never overwrites a variable that is already
set, so a command-line choice is not silently replaced by a stored one.
Persisted overrides do not reach every command
Only the launcher (yggdrasim, yggdrasim-gui, yggdrasim-desktop,
yggdrasim-web-server) and the SCP11 live shell call
apply_persisted_env_overrides() at startup. A standalone console script
such as yggdrasim-scp03 or yggdrasim-card-bridge reads the process
environment only. Export the variable in the shell -- or start from the
launcher -- when a stored value has to apply to one of those.
Where an override is stored
| Persistence | File | Used for |
|---|---|---|
| runtime root | state/env_overrides.json under the runtime root |
Most flags. |
| home | ~/.yggdrasim/env_overrides.json |
Flags that cannot live inside the runtime root, because selecting the root from inside it would be circular. Currently YGGDRASIM_RUNTIME_ROOT. |
| session only | -- | Never written. Export it in a shell profile to pin it across launches. |
A corrupt overrides file is quarantined rather than deleted, and only registered flag names are read back.
Reading the table
- Accepts -- the exact values the editors write. A toggle writes the on
value and unsets for off, so a shell comparison against
1stays valid. - Applies -- immediately means the running process picks the change up; next launch means the value is read once at startup.
- Persistence -- the file an override lands in, per the table above.
- (sensitive) -- the flag weakens a security posture (insecure TLS, demo keys, the quirks gate, disabling plugins), so the editors ask for confirmation before writing it.
The flags
64 flags in 13 categories, generated from yggdrasim_common/env_flags.py.
Build / runtime
| Variable | Accepts | Default | Applies | Persistence | Summary |
|---|---|---|---|---|---|
YGGDRASIM_FLAVOR |
clean, full, source |
auto-detect (frozen build → clean; source checkout → source) | next launch | session only | Force build flavor (clean / full / source) |
YGGDRASIM_RUNTIME_ROOT |
path | source checkout: repo root. Frozen build: YggdraSIM-data next to the exe, else ~/YggdraSIM-data. | next launch | home | Force the writable runtime root |
Card backend
| Variable | Accepts | Default | Applies | Persistence | Summary |
|---|---|---|---|---|---|
YGGDRASIM_CARD_BACKEND |
reader, sim |
reader unless the saved selection picks sim | immediately | runtime root | Force reader vs simulated SIM |
YGGDRASIM_CARD_RELAY_URL |
text | unset (no relay) -- local PC/SC or simulator | immediately | runtime root | Remote HIL card-relay URL |
YGGDRASIM_SIM_QUIRKS |
path | Workspace/SIMCARD/sim_quirks.py (reseeded from template on first run) | immediately | runtime root | Override the simulated-SIM quirks file |
YGGDRASIM_SIM_ISDR_CONFIG |
path | Workspace/SIMCARD/isdr_config.json | immediately | runtime root | Override the simulated-ISD-R personality JSON |
YGGDRASIM_SIM_EIM_IDENTITY |
path | Workspace/SIMCARD/eim_identity.json | immediately | runtime root | Override the simulated default BF55 eIM identity |
YGGDRASIM_SIM_EUICC_STORE |
path | Workspace/SIMCARD/euicc_store | immediately | runtime root | Override the simulated eUICC store root |
YGGDRASIM_SIM_PROFILE_STORE |
path | derived per-EID under the eUICC store root | immediately | runtime root | Override the simulated profile artifact directory |
Simulator behaviour
| Variable | Accepts | Default | Applies | Persistence | Summary |
|---|---|---|---|---|---|
YGGDRASIM_ALLOW_QUIRKS |
1 / unset |
unset → quirks files are refused | immediately | runtime root | (sensitive) Allow loading Python quirks files |
YGGDRASIM_DISABLE_QUIRKS |
1 / unset |
unset → quirks are loaded per YGGDRASIM_ALLOW_QUIRKS | immediately | runtime root | Kill switch for simulator quirks |
YGGDRASIM_SIM_DEBUG_FAULTS |
1 / unset |
unset → quiet | immediately | runtime root | Log simulator fault-injection decisions verbosely |
YGGDRASIM_ENABLE_TUAK |
1 / unset |
unset → MILENAGE only | immediately | runtime root | Enable TUAK auth algorithm in the simulator |
Plugins
| Variable | Accepts | Default | Applies | Persistence | Summary |
|---|---|---|---|---|---|
YGGDRASIM_ALLOW_PLUGINS |
1, 0 |
unset → plugins refused | next launch | runtime root | Opt in to runtime plugin loading |
YGGDRASIM_DISALLOW_PLUGINS |
1 / unset |
unset → still requires YGGDRASIM_ALLOW_PLUGINS=1 | next launch | runtime root | (sensitive) Hard-lock: refuse every plugin |
Demo keys gate
| Variable | Accepts | Default | Applies | Persistence | Summary |
|---|---|---|---|---|---|
YGGDRASIM_ALLOW_DEMO_KEYS |
1 / unset |
unset → banner is printed when demo keys are detected | immediately | runtime root | (sensitive) Silence the SCP03 / SCP80 demo-keys warning |
YGGDRASIM_REQUIRE_NON_DEMO_KEYS |
1 / unset |
unset → demo keys only emit a warning | immediately | runtime root | Fail fast when demo keys are loaded |
SCP11 TLS
| Variable | Accepts | Default | Applies | Persistence | Summary |
|---|---|---|---|---|---|
YGGDRASIM_SCP11_ALLOW_INSECURE_TLS |
1 / unset |
unset → unpinned request traffic is refused | immediately | runtime root | (sensitive) Allow unpinned SCP11 ES9 request traffic |
YGGDRASIM_SCP11_REQUIRE_PINNED_TLS |
1 / unset |
unset → opt-in still possible | immediately | runtime root | Hard-lock: refuse unpinned SCP11 request traffic |
YGGDRASIM_SCP11_ALLOW_TLS_INTROSPECTION |
1 / unset |
unset → first-contact chain reads are refused | immediately | runtime root | (sensitive) Allow read-only TOFU chain reads on first contact |
YGGDRASIM_SCP11_REQUIRE_PINNED_TLS_INTROSPECTION |
1 / unset |
unset → ALLOW_TLS_INTROSPECTION=1 still required | immediately | runtime root | Hard-lock: refuse TOFU chain reads |
SCP11 local SAIP decode
| Variable | Accepts | Default | Applies | Persistence | Summary |
|---|---|---|---|---|---|
YGGDRASIM_SCP11_SAIP_DECODE_TIMEOUT_SECONDS |
number | unset → built-in default (see SCP11/local_access/session.py) | immediately | runtime root | Extend the SAIP decode timeout for LocalSMDPP |
YGGDRASIM_SCP11_ALLOW_FULL_SAIP_DECODE |
1 / unset |
unset → compact decode only | immediately | runtime root | Allow expensive full SAIP decode on LocalSMDPP profiles |
Debug
| Variable | Accepts | Default | Applies | Persistence | Summary |
|---|---|---|---|---|---|
YGGDRASIM_GLOBAL_DEBUG |
1 / unset |
unset → per-module debug stays opt-in | immediately | runtime root | Enable verbose debug across modules |
HIL bridge
| Variable | Accepts | Default | Applies | Persistence | Summary |
|---|---|---|---|---|---|
YGGDRASIM_HIL_CAPTURE_INTERFACE |
text | lo0 on macOS, lo elsewhere | immediately | runtime root | Network interface Wireshark / tshark listen on |
YGGDRASIM_HIL_WIRESHARK_BIN |
path | shutil.which('wireshark') | immediately | runtime root | Explicit Wireshark binary path |
YGGDRASIM_HIL_TERMSHARK_BIN |
path | shutil.which('termshark') | immediately | runtime root | Explicit termshark binary path |
YGGDRASIM_HIL_TERMSHARK_WARMUP_SECONDS |
number | 2.0 | immediately | runtime root | Warm-up delay before starting the bridge after termshark |
YGGDRASIM_HIL_TUI_TERM |
text | auto-detect (prefers screen-256color / tmux-256color / xterm-256color) | immediately | runtime root | Override the TERM value used by the HIL live-decode TUI |
YGGDRASIM_HIL_RELAY_SESSION_RESET |
1 / unset |
enabled | immediately | runtime root | Power-cycle the card at relay-session boundaries |
YGGDRASIM_HIL_SIMTRACE_RESET |
text | usb-reset | immediately | runtime root | How the supervisor clears the SIMtrace2 board before a session |
YGGDRASIM_HIL_UHUBCTL_LOCATION |
text | unset (port-power reset disabled) | immediately | runtime root | Hub location for the port-power SIMtrace2 reset |
YGGDRASIM_HIL_UHUBCTL_PORT |
text | unset (all ports on the hub) | immediately | runtime root | Hub port for the port-power SIMtrace2 reset |
YGGDRASIM_HIL_UHUBCTL_BINARY |
path | uhubctl (resolved from PATH) | immediately | runtime root | Path to the uhubctl binary |
YGGDRASIM_RSPRO_ASN |
path | built-in module shipped with Tools/HilBridge | immediately | runtime root | Override the RSPRO ASN.1 module path |
External tool locators
| Variable | Accepts | Default | Applies | Persistence | Summary |
|---|---|---|---|---|---|
YGGDRASIM_SAIP_TOOL |
text | shutil.which('saip-tool') | immediately | runtime root | Explicit saip-tool binary or command |
YGGDRASIM_SAIP_TOOL_TIMEOUT_SECONDS |
number | built-in default (see Tools/ProfilePackage/saip_tool.py) | immediately | runtime root | Default timeout for saip-tool subprocess calls |
YGGDRASIM_SAIP_TOOL_CACHE_MAX_BYTES |
integer | built-in default (see Tools/ProfilePackage/saip_tool.py) | immediately | runtime root | Cap for the on-disk SAIP tool decode cache |
YGGDRASIM_SAIP_UNIVERSAL_TOKENS |
path | ~/.yggdrasim/saip_universal_tokens.csv | immediately | runtime root | Universal placeholder test-value list for SAIP templates |
YGGDRASIM_SAIP_TOKEN_LISTS |
path | ~/.yggdrasim/saip_token_lists/ | immediately | runtime root | Library of profile-specific placeholder test-value lists |
YGGDRASIM_SAIP_PE_LIBRARY |
path | ~/.yggdrasim/saip_pe_library/ | immediately | runtime root | Library of saved profile elements for the SAIP workbench |
YGGDRASIM_SAIP_UNIVERSAL_DEFAULTS |
1 / unset |
unset → templates are seeded from the list | immediately | runtime root | Seed opened templates from the universal test-value list |
YGGDRASIM_SUCI_TOOL |
text | shutil.which('suci-keytool') | immediately | runtime root | Explicit suci-keytool binary or command |
YGGDRASIM_SUCI_TIMEOUT |
number | built-in default (see Tools/SuciTool/tool.py) | immediately | runtime root | Default timeout for suci-keytool subprocess calls |
YGGDRASIM_EUM_SESSION_KEYS |
path | unset → no session key material available | immediately | runtime root | Path to the EUM session keys JSON repository |
Session recording
| Variable | Accepts | Default | Applies | Persistence | Summary |
|---|---|---|---|---|---|
YGGDRASIM_SESSION_APDU_TRACE_CAP |
integer | 50000 | immediately | runtime root | Soft cap on APDU events per session recording |
Appearance
| Variable | Accepts | Default | Applies | Persistence | Summary |
|---|---|---|---|---|---|
YGGDRASIM_CLI_THEME |
nord, catppuccin-frappe, catppuccin-latte, catppuccin-macchiato, catppuccin-mocha, dracula, github-dark, github-light, graphite-light, gruv-dark, ink-light, islands-light, matrix, mono, nord-light, ocean-dark, oneot-dark, oneot-light, solarized-dark, solarized-light, tokyo-night |
nord (the canonical YggdraSIM palette) | next launch | runtime root | Terminal colour palette for the CLI and the shells |
Universal GUI
| Variable | Accepts | Default | Applies | Persistence | Summary |
|---|---|---|---|---|---|
YGGDRASIM_GUI_HOST |
text | 127.0.0.1 | next launch | runtime root | Desktop GUI bind host |
YGGDRASIM_GUI_PORT |
integer | 27853 | next launch | runtime root | Desktop GUI bind port |
YGGDRASIM_GUI_SERVER_HOST |
text | 0.0.0.0 (SSH-tunnel-friendly: prefer 127.0.0.1) | next launch | runtime root | (sensitive) Remote lab GUI bind host |
YGGDRASIM_GUI_SERVER_PORT |
integer | 27854 | next launch | runtime root | Remote lab GUI bind port |
YGGDRASIM_GUI_TOKEN |
text | unset → auto-generated for --gui, rejected for --web-server | next launch | session only | (sensitive) Bearer token for the GUI API (inline) |
YGGDRASIM_GUI_TOKEN_FILE |
path | unset | next launch | runtime root | (sensitive) Path to a bearer-token file for the GUI API |
YGGDRASIM_GUI_FS_ROOTS |
path | unset -> whole filesystem for --gui, shortcut roots for --web-server | next launch | runtime root | Directories the in-app file picker may list |
YGGDRASIM_GUI_TLS_CERT |
path | unset (plain HTTP unless --tls-self-signed is passed) | next launch | runtime root | TLS certificate path for --web-server |
YGGDRASIM_GUI_TLS_KEY |
path | unset | next launch | runtime root | (sensitive) TLS private key path for --web-server |
YGGDRASIM_GUI_ALLOW_ORIGIN |
text | unset → deny-all (same-origin SPA only) | next launch | runtime root | Additional CORS origin(s) for --web-server |
YGGDRASIM_GUI_IDLE_SECONDS |
integer | 1800 | next launch | runtime root | WebSocket idle cutoff for GUI shell sessions |
YGGDRASIM_GUI_PATH_ALLOWLIST |
text | unset → runtime root + eUICC store + CWD | next launch | runtime root | Extra path roots the GUI is permitted to read |
YGGDRASIM_GUI_WEBVIEW_DEBUG |
1 / unset |
unset → dev tools closed | next launch | runtime root | Open the pywebview dev tools on --gui launch |
YGGDRASIM_GUI_ZOOM |
auto, 0.5, 0.67, 0.75, 0.8, 0.9, 1, 1.1, 1.25, 1.5, 1.75, 2, 2.5, 3 |
1 (native size) | immediately | runtime root | Page zoom of the --gui desktop window |
YGGDRASIM_GUI_GPU |
1 / unset |
unset → GPU off (software drawing, one raster thread) | next launch | runtime root | Let the --gui desktop window draw with the GPU |
YGGDRASIM_GUI_HOST_SHELL |
1 / unset |
unset → Host shell tab is hidden, route refuses connections | next launch | runtime root | (sensitive) Expose the GUI Host-Shell tab (free-form OS shell PTY) |
YGGDRASIM_GUI_CARD_SESSION_IDLE_SECONDS |
integer | 900 (15 minutes) | immediately | runtime root | Idle ceiling for a GUI card session holding a reader |
Related pages
- Runtime Root -- what the runtime root holds
- State Schema -- the files under
state/ - Troubleshooting
- Load Certificates and Configuration