# Core App Startup and Runtime Env Reference

> Updated: 2026-10-07
> Scope: actual `process.env` / `import.meta.env` usage in `apps/core-app/src`

## Startup and fallback status

### 1) Assistant startup state (current)

- `assistantModule` is always registered in the Core App startup module list; there is no environment-variable gate or Assistant-specific `shouldSkip` branch.
- Product availability is controlled by persisted App Settings. The host repairs missing `assistant.enabled` to `false`, so the Assistant remains opt-in without changing module startup semantics.
- Result: operators must use Settings rather than the removed `TUFF_ENABLE_ASSISTANT_EXPERIMENT` flag; startup no longer reports the old optional-module or environment-gate messages.

### 2) dev.source probe + local fallback (fixed)

- `DevPluginLoader` probes remote `manifest.json` first.
- If remote probe fails:
  - fall back to local `manifest.json` + local assets for current runtime only;
  - runtime overrides `dev.source=false` (not persisted);
  - records `DEV_SOURCE_FALLBACK_LOCAL` as warning.
- `REMOTE_MANIFEST_FAILED` remains fatal only when both remote and local fallback fail.

## Plugin Issue Codes (quick lookup)

| Code                              | Default severity | Meaning                                                                                             |
| --------------------------------- | ---------------- | --------------------------------------------------------------------------------------------------- |
| `MISSING_MANIFEST`                | error            | `manifest.json` missing                                                                             |
| `INVALID_MANIFEST_JSON`           | error            | manifest parse/load failed                                                                          |
| `NAME_MISMATCH`                   | error            | manifest name mismatches directory name                                                             |
| `MANIFEST_MISSING_NAME`           | error            | missing `name`                                                                                      |
| `MANIFEST_MISSING_VERSION`        | warning          | missing `version`                                                                                   |
| `CATEGORY_MISSING`                | error            | `category` required for current `sdkapi`                                                            |
| `SDKAPI_BLOCKED`                  | error            | plugin is blocked because `sdkapi` is missing, invalid, unsupported, or below the enforced baseline |
| `PERMISSION_MISSING`              | warning          | required permissions not granted                                                                    |
| `UNKNOWN_PERMISSION_IDS`          | warning          | unknown permission IDs declared                                                                     |
| `INVALID_FEATURE_COMMANDS`        | warning          | invalid feature.commands shape                                                                      |
| `OMNI_TRANSFER_SDK_TOO_LOW`       | warning          | omniTransfer declared with low sdkapi                                                               |
| `DUPLICATE_PLUGIN_NAME`           | error            | plugin name collision                                                                               |
| `LOADER_FATAL`                    | error            | fatal loader exception                                                                              |
| `DEV_MODE_ACTIVE`                 | warning          | running from dev source mode                                                                        |
| `DEV_ADDRESS_INVALID`             | error            | invalid `dev.address`                                                                               |
| `DEV_SOURCE_DISABLED_IN_PACKAGED` | warning          | `dev.source` auto-disabled in packaged runtime                                                      |
| `DEV_SOURCE_FALLBACK_LOCAL`       | warning          | remote manifest failed, local fallback activated                                                    |
| `REMOTE_MANIFEST_FAILED`          | error            | remote failed and local fallback also failed                                                        |
| `DEV_SERVER_DISCONNECTED`         | warning          | dev server heartbeat disconnected                                                                   |
| `LIFECYCLE_SCRIPT_FAILED`         | error            | prelude lifecycle script failed                                                                     |
| `RUNTIME_ERROR`                   | error            | runtime lifecycle execution error                                                                   |
| `AUTO_DISABLED_EXCESSIVE_ERRORS`  | error            | auto-disabled after burst runtime errors                                                            |
| `INVALID_VIEW_PATH`               | error            | invalid interaction/view path                                                                       |
| `PROTOCOL_NOT_ALLOWED`            | error            | remote http/https view blocked in production                                                        |
| `WIDGET_UNSUPPORTED_TYPE`         | error            | unsupported widget type                                                                             |
| `WIDGET_INVALID_DEPENDENCY`       | error            | invalid widget dependency                                                                           |
| `WIDGET_COMPILE_FAILED`           | error            | widget compile failed                                                                               |

## Runtime Env Variables (by category)

### A. Behavior flags / configurable vars

Boolean flags share one parser, `parseBooleanFlag` / `getBooleanEnv` in `@talex-touch/utils/env`: `1` / `true` / `yes` / `on` is on, `0` / `false` / `no` / `off` is off, anything else is the documented default.

| Variable                                                                                  | Purpose                                                                                                   |
| ----------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| `ELECTRON_RENDERER_URL`                                                                   | dev renderer entry URL for main windows and overlays                                                      |
| `NODE_ENV`                                                                                | dev/test/prod behavior branching                                                                          |
| `BUILD_TYPE`                                                                              | build channel for Sentry and runtime labeling                                                             |
| `TUFF_ENABLE_RENDERER_OVERRIDE`                                                           | enables renderer override package                                                                         |
| `TUFF_NEXUS_BASE_URL`                                                                     | explicit Core App runtime Nexus API base override; takes precedence over server mode settings             |
| `TUFF_DISABLE_NATIVE_OCR`                                                                 | disables local OCR provider                                                                               |
| `TUFF_DISABLE_NATIVE_AUDIO`                                                               | disables the native audio capture addon (dictation reports it as switched off)                            |
| `TUFF_DISABLE_NATIVE_SCREENSHOT`                                                          | disables the native screenshot backend                                                                    |
| `TUFF_DISABLE_GLOBAL_SHORTCUTS`                                                           | `1` skips global shortcut registration                                                                    |
| `TUFF_OPAQUE_WINDOWS`                                                                     | forces opaque windows (no vibrancy / Mica); the recovery switch when effects break the launcher           |
| `TUFF_CLIPBOARD_NATIVE_WATCH`                                                             | native clipboard change watcher instead of polling                                                        |
| `TUFF_FILE_PROVIDER_BASE_WATCH_PATHS`                                                     | overrides the file provider's base watch roots                                                            |
| `TUFF_DB_AUX_ENABLED`                                                                     | auxiliary (recommendation / telemetry) database; default on                                               |
| `TUFF_DB_SEARCH_SPLIT_ENABLED`                                                            | search index in its own `search-index.db`; default on, `0` is the kill switch back to the shared file     |
| `TUFF_DB_QOS_ENABLED`                                                                     | database write QoS scheduler; default on                                                                  |
| `TUFF_STARTUP_DEGRADE_ENABLED`                                                            | 120 s startup write-degrade window; default on                                                            |
| `TUFF_STARTUP_ANALYTICS_ENABLED`                                                          | startup analytics collection; default on                                                                  |
| `TUFF_RECO_TIME_STATS_REBUILD`                                                            | `1` rebuilds recommendation time stats from usage logs                                                    |
| `TUFF_INTELLIGENCE_CONTEXT_COREBOX_ONLY`                                                  | `1` rejects intelligence context sessions not owned by CoreBox                                            |
| `TUFF_AGENT_TOOL_CONFIRM_TIMEOUT_MS`                                                      | agent tool confirmation timeout (minimum 250)                                                             |
| `TUFF_SENTRY_TRACES_SAMPLE_RATE`                                                          | overrides the Sentry traces sample rate                                                                   |
| `TUFF_PERF_STARTUP_LAG_GRACE_MS`                                                          | event-loop lag grace after startup (default 2500)                                                         |
| `TUFF_V8_JITLESS`                                                                         | `1` starts V8 with `--jitless` (macOS Tahoe crash workaround; slower JS)                                  |
| `TUFF_TRACE_DEPRECATION`                                                                  | `1` enables Node deprecation traces                                                                       |
| `TUFF_PLUGIN_TRUST_ROOTS_JSON`                                                            | replaces the built-in plugin signing trust roots                                                          |
| `TUFF_PLUGIN_REVOKED_PUBLISHER_KEYS_JSON`                                                 | revoked plugin publisher key ids                                                                          |
| `TUFF_PI_CLI_PATH` / `TUFF_OMP_CLI_PATH` / `TUFF_CODEX_CLI_PATH` / `TUFF_CLAUDE_CLI_PATH` | pins the executable of the respective local AI CLI                                                        |
| `TUFF_OMP_AGENT_DIR`                                                                      | omp agent directory (default `~/.omp/agent`)                                                              |
| `TUFF_DEV_SERVER_HOST` / `TUFF_DEV_SERVER_PORT`                                           | dev renderer server bind address (electron-vite config)                                                   |
| `TUFF_DEV_PARENT_PID`                                                                     | set by the dev wrapper; the app exits when that process is gone                                           |
| `TALEX_CONFIG_STORAGE_BACKEND`                                                            | `sqlite` (default) or `legacy` app-config backend                                                         |
| `TALEX_EVERYTHING_SDK_PATH`                                                               | custom Everything SDK addon path                                                                          |
| `TALEX_EVERYTHING_DLL_PATH`                                                               | Windows `Everything64.dll` path for the native addon (CI sets it; the provider also writes it at runtime) |
| `TALEX_FILE_PROVIDER_EXTRACT_ICONS`                                                       | file icon extraction switch                                                                               |
| `TALEX_PLUGIN_LOG_STDOUT`                                                                 | mirrors plugin logs to stdout                                                                             |

### B. Internal bootstrap vars

| Variable                             | Purpose                                     |
| ------------------------------------ | ------------------------------------------- |
| `APP_VERSION`                        | runtime app version injection               |
| `DEBUG`                              | debug logger switch from `debug.talex` file |
| `ELECTRON_DISABLE_SECURITY_WARNINGS` | suppresses Electron security warning logs   |
| `WS_NO_UTF_8_VALIDATE`               | disables optional ws native addon           |
| `WS_NO_BUFFER_UTIL`                  | disables optional ws native addon           |

### C. OS-provided env vars

`HOME`, `LANG`, `LOCALAPPDATA`, `PROGRAMFILES`, `PROGRAMFILES(X86)`, `SystemRoot`, `USERPROFILE`, `WINDIR`, `TERM`, `TERMINAL` are consumed as runtime OS path/shell hints.

### D. Renderer build-time vars

`import.meta.env.DEV` and `import.meta.env.MODE` are consumed in renderer for dev-only UI and mode checks.

### E. Acceptance / benchmark hooks (harness-only)

Set by `scripts/coreapp-packaged-*.ts` for one launch; an ordinary launch has none of them. Production code reads the gates through `src/main/core/acceptance-mode.ts` (`isStartupBenchmarkMode`, `resolveStartupBenchmarkUserDataDir`, `isIsolatedAcceptanceMode`, `isVisibleEvidenceHookEnabled`) rather than `process.env` directly.

| Variable                                                                                   | Purpose                                                                              |
| ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------ |
| `TUFF_STARTUP_BENCHMARK_ONCE`                                                              | timed benchmark launch that exits by itself; also unlocks the visible-evidence hooks |
| `TUFF_STARTUP_BENCHMARK_USER_DATA_DIR`                                                     | isolated userData / sessionData root for that launch                                 |
| `TUFF_STARTUP_BENCHMARK_DIAG_PATH`                                                         | where precore writes its userData diagnostic JSON                                    |
| `TUFF_STARTUP_BENCHMARK_EXIT_DELAY_MS`                                                     | delay before the benchmark launch exits (default 1200)                               |
| `TUFF_PACKAGED_ACCEPTANCE_ISOLATED`                                                        | skips the single-instance lock for an isolated acceptance profile                    |
| `TUFF_VISIBLE_EVIDENCE_AUTH*` / `TUFF_VISIBLE_EVIDENCE_ASSISTANT_IMAGE_TRANSLATE*`         | scripted auth and image-translate outcomes for visible-evidence captures             |
| `TUFF_MCP_SMOKE*`, `TUFF_PRIVACY_SMOKE_EXPECTED_ENTRYPOINT`, `TUFF_STUB_*`, `TUFF_PROBE_*` | smoke-test entry points and CLI stubs                                                |

## Cleanup Candidates (list only, no removal yet)

No pending cleanup candidates right now (all previously listed high/medium/low items have been completed).

## Nexus Runtime API Server Resolution

- Core App runtime API base resolution is centralized in `packages/utils/env.resolveTuffNexusBaseUrl()`. The only external override variable is `TUFF_NEXUS_BASE_URL`.
- Resolution precedence is fixed: explicit `TUFF_NEXUS_BASE_URL` > Settings runtime API server set to local > official `https://tuff.tagzxia.com`.
- Local mode defaults to `http://localhost:3200`, but dev/unpackaged runtime no longer enables local automatically. Local requires an explicit settings toggle or `TUFF_NEXUS_BASE_URL`.
- Website, docs, Dashboard links, and update sources keep the official online URL by default and do not follow runtime API server mode.

## Completed Cleanup

- `trace-warnings`: removed runtime `process.env` assignment in `src/main/polyfills.ts` (2026-03-23).
- `unhandledrejections`: removed runtime `process.env` assignment in `src/main/polyfills.ts` (2026-03-23).
- `VITE_DEV_SERVER_URL` fallback in main: removed `AppProvider` fallback path; unified to `ELECTRON_RENDERER_URL` (2026-03-23).
- `TALEX_WORKFLOW_DEBUG`: removed SID-bound debug toggle and file logging path in TPEX provider (2026-03-23).
- `TUFF_RELEASE_SIGNATURE_*` aliases: removed legacy alias lookup; normalized to `TUFF_UPDATE_*` (2026-03-23).
- `TUFF_OMNIPANEL_SMOKE`: removed startup smoke env gate and related probe logic (2026-03-23).
- `USE_LOCAL_NEXUS`: removed PluginStoreService local Nexus env special-case; normalized to `getTpexApiBase()` (2026-03-23).
- `VITE_NEXUS_URL` / `NEXUS_API_BASE` / `NEXUS_API_BASE_LOCAL` / `TPEX_API_BASE` / `AUTH_ORIGIN` / `TUFF_LOCAL_BASE_URL`: no longer participate in Core App runtime API base resolution; use `TUFF_NEXUS_BASE_URL` instead (2026-05-12).
- `DIST` / `PUBLIC`: removed the runtime `process.env` writes in `src/main/polyfills.ts`; nothing read them (2026-10-07).
- `TUFF_ENCRYPTION_KEY`: removed the secret injection and "official build" echo from the release workflow; no code reads it (2026-10-07).
- `ELECTRON_PLATFORM` / `ELECTRON_ARCH`: removed from `scripts/build-target.js`; neither the repo nor electron-builder reads them (2026-10-07).
- `BUILD_MAC_LSUIELEMENT`: alias dropped; `TUFF_MAC_LSUIELEMENT` is the only name (2026-10-07).
- `TUFF_RELEASE_API_URL` / `TUFF_BUILD_SIGNATURE_URL` / `TUFF_BUILD_SIGNATURE_KEY_URL` / `TUFF_UPDATE_SIGNATURE_KEY_URL` / `TUFF_UPDATE_SIGNATURE_PUBLIC_KEY_URL`: delisted above; no reader is left in `apps/core-app/src` (2026-10-07).
- `smoke:omnipanel` script: removed, it only set the already-removed `TUFF_OMNIPANEL_SMOKE` (2026-10-07).
- `apps/core-app/.env` (`VITE_CLERK_PUBLISHABLE_KEY`, `VITE_NEXUS_URL`): deleted; neither key had a reader (2026-10-07).
- Boolean flag parsing: the ten local copies collapsed onto `@talex-touch/utils/env` (2026-10-07).