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​

For Palette SDK 3.0 or above, sima-cli sdk setup supplies CODE_SERVER_PASSWORD in the container environment. Run neat again to retrieve it and enter it when code-server prompts you. URLs contain no password or token. neat --json adds codeUI with backend, auth, password, localUrl, and remoteUrl; treat this output as credential-bearing. The published codeUIHttps.host port from the SDK port map takes precedence over the container port.

The installed code-server executable selects this behavior; merely setting CODE_SERVER_PASSWORD does not change legacy OpenVSCode behavior. CODE_SERVER_HTTPS_PORT and CODE_SERVER_WORKSPACE override their legacy equivalents. CODE_SERVER_WITHOUT_PASSWORD=1 reports auth: "none" and omits the password value. Legacy OpenVSCode images retain token URLs.

  • 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 — output wait for input-mode Graph::run() and supported seeded build preflight.
    • Run::run(..., timeout_ms) / Model::run(..., timeout_ms) — per-call output wait; -1 is unlimited, as in Run::pull(-1).
  • 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> — fallback for those Graph::run() / preflight output waits (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_ASYNC_TPUT_DIAG=1 — async throughput diagnostics.
  • SIMA_ASYNC_WARMUP=<n> — async warmup frames.
  • SIMA_PERF_POWER=1 — enable board power capture from Sentinel in perf scenarios.
  • SIMA_PERF_POWER_INTERVAL_MS=<ms> — deprecated and ignored; Sentinel samples every 2 s.
  • 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_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 a unique, lock-protected proc_run_* 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 abandoned proc_run_* extraction roots on startup using ownership locks (default 1). Legacy proc_<pid> roots must be removed manually once unused.
  • 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.

Kernel metadata qualification​

ProcessCVU stages execute through Runtime's neatkernelrunner by default. No build option or environment variable selects the old ProcessCVU plugin.

  • SIMA_CORE_COMPACT_METADATA=1 — permit compact TensorSet and typed current-frame metadata on the owned direct runner-to-appsink edge after capability agreement. Requires no incompatible boundary, debug, or flow observer. Standard owned stage/element timings remain enabled and support both representations. Unrepresented extensions retain legacy dynamic metadata.

Do not attach legacy-only probes to a compact edge. Without capability agreement, Runtime preserves legacy metadata for unknown consumers and observers; execution still uses neatkernelrunner. This metadata option makes no latency or throughput guarantee.

Package and weekly qualification (test-only)​

  • SIMA_TEST_PACKAGE_INVENTORY=<absolute-path> — expected package controls and payload identity generated from selected, verified distribution archives by tools/ci/verify_core_dist.py --write-package-inventory. Required by the installed DevKit package-inventory test. It does not redirect dpkg to a private prefix and is not an installation-result report.
  • SIMA_TEST_PLATFORM_BASELINE=<absolute-path> — native platform presence, absence, package identities and OTA availability/identity captured before installation with tools/ci/verify_core_dist.py --capture-platform-baseline. Required by the installed DevKit package-inventory test alongside the selected package inventory. Do not regenerate this baseline from the post-install state.
  • SIMA_RUN_MNIST_PREPROC_CHANNELS1=1 — opt in to the long MNIST preproc accuracy test. Obtain this value from tools/ci/prepare_weekly_fixtures.py after fixture validation instead of setting it merely to suppress a skip. Local launchers consume --environment-json; CI consumes the same mapping through --github-env.

See Test Requirements for fixture-group selection and installed-package profiles.

PCIe host and card status​

NEAT_PCIE_SSH_USER selects the card SSH user (default sima). NEAT_PCIE_SSH_KEY selects a private key (default ~/.ssh/sima_neat_pcie_ed25519); existing SSH configuration and agent authentication remain available. --offline skips Internet update checks but still reads attached cards over local SSH. PCIe host status skips artifact update checks; use sima-cli neat install core/pciehost/<distro>/<arch>@<ref> to update the host package. neat update does not update PCIe cards.