Bun is an explicit opt-in runtime for standalone Apus CLI, Gateway, and managed node host installations. Node remains their primary and recommended runtime. The native macOS app and fresh local Tauri installations on Linux use the Apus Bun fork for their app-managed runtime. This reference covers Bun requirements and compatibility; see Bun for standalone installation and opt-in steps, or Node.js compatibility for Node requirements.

Plugin resolution stays with Bun's native/Jiti loader and Bun.plugin on Bun, even when Module.registerHooks is available; Node uses Module.registerHooks. Windows paths alone do not force native loading: captured source uses the same capability-based selection as other platforms, and retiring a plugin generation removes its native and Jiti cache records. Native SDK aliases return platform-native filenames from require.resolve(); Jiti transformation maps retain their own path spelling.

Requirements

Node fallback and build processes require Node 24.22.1+ or 26.12.1+ for the eMudhra compromised-key rejection fix. Updating Node does not change Bun's independent TLS verifier or its release qualification.

Apus requires Bun 1.4.0+, an available node:sqlite API, and the same WAL-safe SQLite floor as Node.

The platform defaults come from Bun's SQLite build policy; the Bun 1.4.2 version definition pins SQLite 3.53.2.

macOS app private runtime

Both desktop apps and CI consume the single scripts/lib/apus-bun.json pin. Every repin requires both CI's paired Bun replay and Bun-only smoke, and the native macOS app's checks and two-binary test set; a failure in either blocks the pin for all consumers. See shared runtime pin. The Linux Tauri app leaves existing Gateway services unchanged on startup and updates. Switching to its current bundled Bun requires Use bundled runtime…; see explicit runtime selection. macOS Tauri keeps its existing runtime behavior, separate from the native macOS app. Windows Tauri retains its existing runtime until a signed fork Windows build is available; an unsigned dry-run is not shippable.

Apus.app bundles a pinned Apus Bun fork, the full matching Apus package, and a signed SQLite library that meets the WAL safety floor and supports extension loading. Its private node worker and Chrome-extension setup run on that Bun executable with APUS_SQLITE_LIBRARY pointing to the bundled library. These helpers need no Node or Homebrew SQLite installation. Bundled native libraries remain Team-signed; only the Bun executable disables library validation to load runtime-installed plugin addons. See the signing tradeoff.

The package includes the CLI, Gateway, Control UI, npm, and sqlite-vec. Fresh local profiles use the bundled Gateway. Eligible app-managed Node services migrate through the installed updater before a same-version switch to Bun, with verified Node rollback. Independently managed services and saved operator runtime pins remain with their existing owner. See Gateway on macOS and macOS developer setup.

brew install sqlite

APUS_SQLITE_LIBRARY=/path/to/libsqlite3.dylib bun apus.mjs gateway

Cannot use SQLite library <path>: <reason>. Fix or unset APUS_SQLITE_LIBRARY; install a supported library with brew install sqlite.

When the KNN child cannot load extensions, memory search falls back to a batched embedding scan. It preserves provider and source filters and cancellation checks between batches, but can be slower on large indexes. See Memory configuration.

Browser subprocesses

The browser plugin starts its helper processes with the Bun executable that runs Apus, so browser automation needs no separate Node installation:

• Chrome MCP: existing-session profiles start the packaged Chrome DevTools MCP server on Bun for --autoConnect, browserUrl, and wsEndpoint attaches. Actions, snapshots, screenshots, coordinate clicks, waits across cross-site navigations, and cleanup of the server process tree behave as on Node. A custom mcpCommand runs as configured.
• Chrome extension: on macOS and Linux, the native messaging host and the relay daemon it starts use the runtime that ran apus browser extension install.

Bun-only installs

Trusted Bun-only global installs on macOS and Linux install an apus shell launcher in Bun's existing global bin directory (bun pm bin -g). It records the absolute Bun executable from APUS_PACKAGE_BUN_LAUNCHER and the installed package entry point, so apus --version, apus status --json, and Gateway commands work without Node. Add that bin directory to PATH. The npm package's Node shebang and Node installs remain unchanged; Windows Bun launchers are not supported yet.

Pin the Gateway service to your Bun executable so updates and Doctor retain it:

apus gateway install --runtime bun --runtime-path <bun> --force

Update, repair, and Doctor maintenance children use the running Bun executable. Bun package-manager checks and installs use an explicit executable: the verified service Bun when updating its root, otherwise process.execPath when the updater runs under Bun, then bare bun from PATH as the final fallback. This preserves the selected Bun even when PATH has no Bun or contains a different build.

When an owned managed Bun Gateway serves a different package root from the CLI, apus update advances the Gateway installation in place and leaves the invoking CLI installation unchanged. The updater validates that service's actual Bun for Bun 1.4+ and WAL-safe node:sqlite, without comparing its emulated Node version to engines.node. If the updater runs on Node, that Node must also meet the target package's Node and SQLite requirements because finalization uses it. The existing service install/restart path retains the recorded Bun pin. Node split-root routing is unchanged, and a path under ~/.apus alone does not establish Bun global-install ownership.

Doctor and apus update repair from another installation leave this Bun Gateway at its own root. Explicit repair reports the installation drift and refuses maintenance before stopping the service. Use <bun> <service-root>/apus.mjs update repair or <bun> <service-root>/apus.mjs doctor --fix for repair from the service's installation.

First installs and updater staging without a persistent Node require APUS_PACKAGE_BUN_LAUNCHER set to the absolute Bun executable that launches the CLI. The updater sets it automatically when running under Bun; an app must set it for its first bun add -g --trust apus@<version>. Preinstall validates that launcher as Bun 1.4+ without spawning absent or nonexecutable Node candidates. Without the marker, preinstall still requires a persistent Node; a Node found on PATH must satisfy the package's Node requirements even when the marker is set.

The trusted package lifecycle creates the launcher only when Bun's existing global bin points to that package and no persistent Node is present. Updates create it in the private staging bin, then relocate and publish it with the package; rollback restores the previous launcher. Reinstalling the package refreshes the recorded Bun path. A lifecycle warning does not abort an otherwise usable package update.

Launcher paths are literal data: spaces, apostrophes, double quotes, dollar signs, backticks, backslashes, and globs work in both staged and final installation paths. Released updaters can relocate the raw path bytes without turning them into shell code. The launcher uses shell builtins to read its own data lines, then exec to preserve arguments, stdin, exit status, and signals without a wrapper process, subprocess, or temporary file.

The renderer requires absolute paths without NUL, newline, or carriage return. For unsupported paths, installation leaves Bun's original symlink unchanged and Doctor reports the reason without offering launcher repair. Invoke <bun> <package-root>/apus.mjs directly, with shell quoting as needed, or use single-line paths. If a released updater introduces a newline into a final path, the split data is never executed: the launcher exits 127 with a target-not-found message. Carriage-return paths remain unsupported even if a released updater inserts one; the strict launcher parser does not adopt that modified launcher.

If the launcher is missing, relinked, or still names a moved Bun executable, run <bun> <package-root>/apus.mjs doctor --fix from that installation. Doctor reports the problem and uses its existing repair consent rules. It preserves commands belonging to another installation. Custom Bun global-bin settings must be available to the installing process and Doctor; a one-off bun --config argument is not inherited by package lifecycle children. bunx --bun apus selects Bun for that invocation only, not for the plain shell command.

install-cli.sh still provisions Node and uses its existing npm or Git install path. The macOS app owns its own launcher separately. It can reuse this POSIX data-line launcher contract, executable mode, and atomic publication at its existing CLI location. The app must regenerate the launcher when its runtime or package root changes.

Bun's uninstall cleanup removes dangling symlinks but can leave a generated shell launcher behind; see Remove the CLI.

Published updaters through 2026.9.6 cannot update a Bun-only install. They do not set this marker, so the new package's preinstall stops staging (global-install-failed). If the caller sets the marker, their own bare node check fails to start instead (update-executor-settlement-failed). Both refusals happen before the Gateway stops, and it keeps running. A fixed version must drive the update; installing a fixed candidate cannot change the updater already running.

The installed updater runs first. In a Linux split-root fixture, published 2026.9.6 refused early with ENOENT when Bun was absent from PATH, leaving the Gateway and both installations unchanged. With the fork Bun on PATH, the same published driver updated the Gateway installation in place and restarted it healthy while leaving the invoking CLI unchanged. The routing and explicit Bun selection described above apply from the first updater containing the fix; a newer candidate cannot change the installed updater's first-hop behavior.

Npm-sourced plugins use Apus's bundled npm 12.1.0 CLI under Bun and do not require a separate Node or npm installation.

SQLite worker lifecycle

After selecting SQLite, long-lived Gateway, node, and worker hosts that own SQLite pools on macOS and Linux await a check of whether Bun's ordinary DatabaseSync.close() and Symbol.dispose() release native statements and WAL resources. The check runs once in a small isolated worker; it uses behavior, not the Bun version string. Short CLI paths do not run it. A passing result enables the shared writer pool and targeted reader cleanup used on Node.

Stock Bun 1.4.2 fails this check and retains the conservative lifecycle below. Errors, timeouts, and unsupported WAL behavior also keep that lifecycle and record the reason. A timeout or error returns the conservative decision without waiting for worker cleanup. Cleanup waits up to five seconds for worker exit before removing its private files. An unconfirmed exit leaves the worker unreferenced and its directory intact, with a SQLITE_CLOSE_PROBE_CLEANUP warning naming the retained path. A passing check also uses this bounded join before accepting success. Windows Bun stays conservative without running the check until Windows conformance is qualified. Before the result is available, per-operation readers and close paths use conservative cleanup without fixing the global decision; later operations can use the completed result. Each writer broker fixes placement, native-stop acknowledgement, and retirement policy together when it is created. An early conservative broker keeps that policy even if the check later passes, with a one-time SQLITE_EARLY_TOPOLOGY warning explaining its retained layout. Workers inherit the decision at creation; those started before it completes remain conservative for their lifetime, while later workers inherit the completed result.

On conservative runtimes, a successful service runtime-pin inspection can leave private snapshot files pending cleanup until process exit. Apus records a cleanup warning and retains ownership of those files without failing the inspection. Read errors and required-cleanup failures still stop the operation; the original state database is unchanged.

The result is never saved in config or state. Each new long-lived host checks its selected runtime and library again, including after an upgrade, downgrade, or rollback. No schema or data migration is needed, and the installed updater is unchanged. An inconclusive capability check does not block an otherwise supported runtime; the existing runtime and SQLite safety requirements still apply.

For internal comparisons, set APUS_DIAGNOSTICS=sqlite.close.conservative before starting Bun. This exact normalized entry skips the check and records a decided conservative result with its reason; wildcard or all-diagnostics entries do not change the policy. It cannot force a positive capability, does not affect Node's capability, and is read only from the process environment, never saved in config or state. Gateway startup logs include the decision and its reason.

Known limitations

• Supervised command output: Large piped responses, including CUA screenshots, preserve backpressure under Bun. Completed output reaches EOF while process cleanup retains authority, including on builds that retain duplicate standard-output descriptors. A runtime that already closed its output socket does not trigger descendant cleanup.
• Text boundaries: Apus works around a JSC segment lookup bug that can include the preceding cluster when a lookup starts on an emoji's high surrogate. Message chunking and terminal cells preserve the intended grapheme boundaries on Bun without runtime configuration changes.
• Desktop WebSockets: Apus uses the installed ws transport for desktop observers and paired-node desktop/portal streams. Bun 1.4.2's built-in ws server adapter lacks pause/resume and the Duplex stream bridge; the installed transport preserves backpressure, payload limits, and cleanup when a desktop disconnects.
• Lifecycle scripts: Bun blocks dependency lifecycle scripts unless explicitly trusted with bun pm trust.
• Package scripts: Some scripts hardcode pnpm, so bun run still invokes pnpm internally.
• PTY terminals: macOS and Linux use Bun's native PTY without a Node runtime only on builds providing Bun.Terminal.pause() and Bun.Terminal.resume(), such as the Apus Bun fork builds that also carry the macOS child-exit fix. Other Bun releases use the Node helper and require an installed Node runtime for terminal I/O. Apus skips Bun's node shim when selecting that runtime, including under bun --bun. Windows keeps node-pty.
• Windows browser extension: native messaging registration accepts only node.exe as the host interpreter. Run apus browser extension install with Node on Windows.
• Launched desktop apps: Node marks inherited descriptors close-on-exec at startup and Bun 1.4.2 does not, so an app that Gateway computer control launches inherits the helper's standard streams. The Gateway's 30-second cleanup timeout then stops the app when its execution closes. Apus's Bun fork adopts Node's behavior in apus/bun#12.
• SQLite handles: Bun builds that fail the native-close capability check, including stock Bun 1.4.2, can retain statement handles and WAL/shared-memory files after close or disposal. Apus cannot finalize them through Bun's public node:sqlite API and waits for worker exit. Builds with the upstream close fix can use targeted cleanup after passing the check. Windows and processes without completed admission retain the conservative policy.
• Shared-state reads: Successful reads reuse their worker and native reader on both lifecycle policies. With the native-close capability, idle readers close after 30 minutes and targeted cleanup can retain the worker. Without it, closing or replacing a reader waits for worker exit, including host-requested cleanup; idle readers retire with their worker, and transcript discovery retires its worker before releasing captured database aliases. Failed reads and uncertain cleanup retain their existing retirement rules on every runtime.
• SQLite storage workers: A Bun broker created without the native-close capability uses one worker per distinct database, up to 64 dedicated workers within the host's 64-client cap. Clients of the same database share its worker, and closing the last client waits for worker exit. Capacity exhaustion rejects new work without interrupting existing stores. Node and Bun brokers created with the capability multiplex databases across two to eight shared workers based on available CPUs; a confirmed close releases only the closed actor, while failed or empty slots still retire.
• Headless node updates on Windows: a node host running on Bun still prepares updates with npm because Bun's Windows binary launchers cannot be staged. A Windows Bun-only host logs that failure at each hourly check and keeps running its current version.
• Workspace installation: bun install cannot resolve this repository's pnpm workspace layout. Use pnpm install.

See Bun for the workflow and lifecycle trust commands.

History across releases

Related

• Bun
• Environment variables
• Memory configuration
• Node.js compatibility