Skip to main content

Environment variables

This page consolidates environment variables used by the runtime, builder, and SDK tooling. Many are debug/diagnostic toggles; most users can ignore them unless troubleshooting.

For the exhaustive detected list, see Environment Variable Inventory.

Note: Some knobs are internal/test-only and may change. They are included here because they appear in code paths today.

SDK web access​

  • NFS_SERVER_HOST_IP=<address> — SDK host address used to construct remote Insight and browser-based VS Code URLs. This is normally supplied by sima-cli sdk setup.
  • CONTAINER_HOST_IP=<address> — legacy fallback for the remote host address when NFS_SERVER_HOST_IP is unavailable.
  • OPENVSCODE_SERVER_HTTPS_PORT=<port> — HTTPS port for browser-based VS Code. If unset, neat does not display VS Code URLs.
  • OPENVSCODE_SERVER_TOKEN=<token> — browser-based VS Code access token. The value generated by sima-cli is URL-safe. Treat URLs containing this token as credentials and do not share them.
  • OPENVSCODE_WORKSPACE=<path> — workspace opened by browser-based VS Code (default /workspace).
  • OPENVSCODE_SERVER_WITHOUT_TOKEN=1 — run and advertise browser-based VS Code without token authentication. Use this only in a trusted local environment; never enable it when the service is reachable from an untrusted network.
  • SIMA_DEBUG_PROFILE=<components> — unified debug enable switch for common diagnostics.
    • Components: pipeline, graph, gst, appsink, inputstream, or all.
    • Multiple components can be comma/space separated (for example pipeline,gst,inputstream).
  • SIMA_DEBUG_LEVEL=<0..3> — debug verbosity level used by unified profile (default 1).
    • 0: disabled
    • 1: core debug logs
    • 2: verbose diagnostics/buffer-level tracing
    • 3: maximum verbosity

Legacy per-variable debug toggles still work and override profile defaults when explicitly set.

Core build/run​

  • SIMA_PIPELINE_STRING_DEBUG=1 — print the final gst-launch string on build.
  • SIMA_PIPELINE_STATE_DEBUG=1 — extra state-change logs.
  • SIMA_PIPELINE_TEARDOWN_DEBUG=1 — logs pipeline teardown steps.
  • SIMA_PIPELINE_DRAIN_BEFORE_TEARDOWN_MS=<ms> — drain time before teardown (default 1500).
  • SIMA_PIPELINE_DRAIN_MIN_OUTPUTS=<n> — minimum outputs to drain before teardown (default 1).

GStreamer init + suppression​

  • SIMA_ALLOW_GST_INIT=1 — allow manual gst_init if already initialized.
  • SIMA_GST_SUPPRESS_JSON_WARNINGS=0/1 — silence JSON warnings (default true).
  • SIMA_GST_SUPPRESS_GOBJECT_ASSERTS=0/1 — silence GLib assert logs (default true).
  • SIMA_GST_SUPPRESS_DEVICE_LOGS=0/1 — silence device logs (default true).

GStreamer timeouts​

  • SIMA_STATE_CHANGE_TIMEOUT_MS=<ms> — pipeline state change timeout (default 15000).
  • SIMA_GST_TEARDOWN_TIMEOUT_MS=<ms> — teardown timeout (default 2000).
  • SIMA_GST_TEARDOWN_REAPER_MS=<ms> — teardown watchdog (default 250).
  • SIMA_GST_TEARDOWN_ASYNC=1 — async teardown.
  • SIMA_GST_POLL_SLICE_MS=<ms> — poll slice for appsink pulls (default 200).
  • Preferred API knobs:
    • ValidateOptions.preroll_timeout_ms — validate() preroll timeout.
    • RunOptions.input_timeout_ms — build()/run() input-mode pull timeout.
  • Legacy fallback env vars (use only when you cannot pass options):
    • SIMA_GST_VALIDATE_TIMEOUT_MS=<ms> — validate() timeout (default 2000/10000).
    • SIMA_GST_RUN_INPUT_TIMEOUT_MS=<ms> — run() input timeout (default 10000).

Diagnostics + probes​

  • SIMA_GST_DOT_DIR=<dir> — dump DOT graphs for pipeline failures/debug.
  • SIMA_GST_BOUNDARY_PROBES=1 — attach boundary flow probes.
  • SIMA_GST_STAGE_TIMINGS=1 — stage timing probes.
  • SIMA_GST_ELEMENT_TIMINGS=1 — element timing probes.
  • SIMA_GST_FLOW_DEBUG=1 — element flow probes.
  • SIMA_GST_ENFORCE_NAMES=1 — enforce name contract on build.
  • SIMA_GST_OPTIONS_DEBUG=1 — log GStreamer options during build.
  • SIMA_GST_BUFFER_DEBUG_LIMIT=<n> — cap buffer debug prints.
  • SIMA_GST_DETESS_INPUT_DEBUG=1 — detess input debug.
  • SIMA_GST_DETESS_OUTPUT_DEBUG=1 — detess output debug.
  • SIMA_GST_DETESS_POOL_DEBUG=1 — detess pool debug.
  • SIMA_GST_APPSINK_BUFFER_DEBUG=1 — appsink buffer debug.
  • SIMA_GST_ALL_BUFFER_DEBUG=1 — verbose buffer debug.
  • SIMA_GST_RUN_INSERT_BOUNDARIES=1 — insert boundaries during run().
  • SIMA_GST_VALIDATE_INSERT_BOUNDARIES=1 — insert boundaries during validate().

Dispatcher / runtime​

  • SIMA_DISPATCHER_TRACE=1 — trace dispatcher steps.
  • SIMA_DISPATCHER_AUTO_RECOVER=0/1 — auto-recover dispatcher (default true).
  • SIMA_ASYNC_TPUT_DIAG=1 — async throughput diagnostics.
  • SIMA_ASYNC_WARMUP=<n> — async warmup frames.
  • SIMA_PERF_POWER=1 — enable SOM PMIC rail power capture in perf scenarios.
  • SIMA_PERF_POWER_INTERVAL_MS=<ms> — power sampling interval (default 100).
  • SIMA_PULL_TIMEOUT_DIAG=0/1 — report on pull timeouts (default true).
  • SIMA_STAGE_DEBUG=1 — StageRun debug logs.

InputStream / Sample debugging​

  • SIMA_INPUTSTREAM_DEBUG=1 — verbose InputStream logs.
  • SIMA_INPUTSTREAM_WARN=1 — warnings on InputStream events.
  • SIMA_INPUTSTREAM_POLL_MS=<ms> — InputStream poll slice (default 50).
  • SIMA_INPUTSTREAM_DOT_ON_TIMEOUT=1 — dump DOT on timeout.
  • SIMA_INPUTSTREAM_META_DEBUG=1 — log GstSimaMeta details.
  • SIMA_INPUTSTREAM_ALLOC_DEBUG=1 — allocation debug.
  • SIMA_INPUTSTREAM_PUSH_TIMING=1 — push timing logs.
  • SIMA_INPUTSTREAM_PREFLIGHT_RUN=1 — preflight run for InputStream.
  • SIMA_SAMPLE_DEBUG=1 — log sample conversions.
  • SIMA_SAMPLE_BYTES=1 — log sample byte sizes.
  • SIMA_SAMPLE_FORCE_BUNDLE=1 — force bundle output for debugging.
  • SIMA_NEAT_CAPS_TRACE=1 — trace Tensor cap derivation.

Preproc / Detess / wiring​

  • SIMA_PREPROC_DEBUG_CONFIG=1 — dump preproc config wiring.
  • SIMA_KEEP_DETESS_CONFIG=1 — keep detess config outputs.
  • SIMA_DETESS_ASSERT_ON_ZERO=1 — assert on zero detess output.
  • SIMA_CLAMP_DETESS_NUM_BUFFERS=1 — clamp detess num-buffers.
  • SIMA_DISABLE_SYNC_NUMBUFFERS_CVU_MLA=1 — disable sync num-buffers clamps.

Model (legacy env var names retained)​

  • SIMA_MLA_NEXT_CPU=<domain> — override MLA next_cpu.

  • SIMA_MPK_EXTRACT_ROOT=<dir> — base directory for model-archive loading. Resolved to an absolute path once per process, so paths rewritten into extracted JSON never depend on the working directory. Authoritative: if it is not writable, loading fails rather than falling back. When unset, the base is the first writable candidate of a mounted NVMe filesystem, /data, TMPDIR, then the working directory. An NVMe candidate must be a writable /dev/nvme* block device on a data mount: root, /boot, /efi and other system mounts are excluded, as are vfat/ISO filesystems. Those checks apply to NVMe discovery; the /data, TMPDIR, and working-directory fallbacks retain their normal filesystem placement. NVMe is preferred for capacity, predictable placement, and avoiding eMMC writes. It is not a decode speedup: this variable selects where output is written, and decode is CPU bound.

    Selection is by writability, not free space. A .tar.gz bounds its inflated size in neither direction, so no capacity requirement is knowable before decoding; space is enforced per chunk while inflating and again from the manifest before extracting. An eligible NVMe is therefore used unconditionally, and one without room fails the load with output_storage_unavailable rather than falling back to eMMC. Free space on that filesystem, or SIMA_MPK_EXTRACT_ROOT pointing elsewhere, is the fix.

  • SIMA_MPK_CLEANUP_EXTRACTED=0/1 — delete per-process extracted model-archive data on normal exit (default 1). With cleanup on, each process extracts into its own proc_<pid> root and removes it at exit. With cleanup off, that process root is kept for inspection and excluded from stale-root garbage collection. It is not automatically discovered or reused by another process; remove it by hand when it is no longer needed.

Model also accepts an already-organized package root containing etc, lib, and share. That directory is used in place without decompression or copying; the caller owns its lifetime and must keep it unchanged while the model is in use. A flat directory produced by tar -xzf is not an organized package and is not accepted directly.

  • SIMA_MPK_EXTRACT_GC_STALE_PROC=0/1 — remove stale dead-proc_* extraction roots on startup (default 1).
  • SIMA_MODEL_TAR=<path> — base model-pack path used by examples/tests. Per-model overrides (SIMA_RESNET50_TAR, SIMA_YOLO_TAR, etc.) still take precedence.
  • SIMA_MPK_EXTRACT_MIN_FREE_BYTES=<bytes> — free space kept in reserve when staging and extracting model archives (default 16 MiB).
  • TMPDIR=<dir> — considered only as a late candidate for the base above, and used directly for staging by callers that select no base of their own. Model loading no longer stages here independently: the inflated snapshot and the extracted package share the selected base. Every load, including metadata-only inspection, decompresses the .tar.gz once into a private directory. During extraction, that filesystem needs room for the inflated snapshot, the package, and SIMA_MPK_EXTRACT_MIN_FREE_BYTES; the 150 MB reference pack's snapshot is about 354 MB. Use a local filesystem — loading fails if free space cannot be read, which a network mount that goes away will do. The staging directory is removed when loading finishes, on success and on failure; an abrupt kill or power loss can leave one behind.

The free-space reserve set by SIMA_MPK_EXTRACT_MIN_FREE_BYTES is best effort. It is checked per chunk during inflation against the filesystem's reported free space, so an unrelated concurrent writer can still exhaust the filesystem between checks; the load then fails with the bytes written and the path it was using.

RTSP / H264​

  • SIMA_H264_SDP_DUMP=<path> — dump H264 SDP to file.
  • SIMA_H264_SPS_FIXUP_STREAM=<path> — fix up SPS in stream.

Test / internal hooks​

  • SIMA_TENSOR_MAPFAIL_DEBUG=1 — log Tensor map failures.