Desktop local development

The desktop dev stack is not a single binary. bun run dev:desktop and bun run dev:desktop:watch run eliza/packages/app-core/scripts/dev-platform.mjs, which orchestrates separate processes: optional one-off vite build, optional repo-root tsdown, then long-lived Vite (when ELIZA_DESKTOP_VITE_WATCH=1), bun --watch API, and Electrobun.

Why orchestrate? Electrobun needs (a) a renderer URL, (b) often a running dashboard API, and (c) in dev, a root dist/ bundle for the embedded Eliza runtime. Doing that manually is error-prone; one script keeps ports, env vars, and shutdown consistent.

Commands

CLI flags (preferred for ad-hoc use; bun run dev:desktop -- --help lists them): --no-api, --force-renderer, --rollup-watch, --vite-force.

Startup tables: the orchestrator, Vite, API, and Electrobun each print a plain-text settings table (columns Setting / Effective / Source / Change) so you can see defaults vs env and how to change a knob. Run without --help to see them in the terminal.

Startup tables and terminal banners

On a TTY, tables may use a Unicode box frame and a large figlet-style title for the subsystem name (orchestrator, Vite, API, Electrobun), with ANSI color (magenta title, cyan frame) unless NO_COLOR is set (FORCE_COLOR can opt in for piped output).

Why: Desktop dev runs four processes with overlapping env (ports, URLs, feature flags). The goal is fast visual scanning of effective values for humans and IDE agents — the same rationale as port pre-allocation and prefixed logs. This is not companion or dashboard UI; it does not ship to end users as product chrome.

Docs: Developer diagnostics and workspace.

Why separate commands? A full production Vite build is still useful when you want parity with shipped assets or when you are not touching the desktop shell UI. bun run dev:desktop:watch points Electrobun at the Vite dev server for HMR, while bun run dev stays on the browser dashboard stack.

Legacy: Rollup vite build --watch

If you explicitly need file output on every save (e.g. debugging Rollup behavior):

ELIZA_DESKTOP_VITE_WATCH=1 bun eliza/packages/app-core/scripts/dev-platform.mjs -- --rollup-watch
# or env-only:
ELIZA_DESKTOP_VITE_WATCH=1 ELIZA_DESKTOP_VITE_BUILD_WATCH=1 bun eliza/packages/app-core/scripts/dev-platform.mjs

Why this is opt-in: vite build --watch still runs Rollup production emits; “3 modules transformed” can still mean seconds rewriting multi‑MB chunks. The default watch path uses the Vite dev server instead.

Environment variables

When default ports are busy

The dev-platform orchestrator runs dev:desktop and bun run dev. Before starting long-lived children it probes loopback TCP starting at:

If the preferred port is already bound, the orchestrator tries preferred + 1, then +2, … (capped), and passes the resolved values into every child (ELIZA_DESKTOP_API_BASE, ELIZA_RENDERER_URL, Vite’s ELIZA_PORT, etc.).

Why pre-allocate in the parent (not only inside the API process): Vite reads vite.config.ts once at startup; the proxy’s target must match the API port before the first request. If only the API shifted ports after bind, the UI would still proxy to the old default until someone restarted Vite. Resolving ports once in dev-platform.mjs keeps orchestrator logs, env, proxy, and Electrobun on the same numbers.

Packaged desktop (local embedded agent): the Electrobun main process calls findFirstAvailableLoopbackPort (packages/app/electrobun/src/native/loopback-port.ts) from the preferred ELIZA_PORT (default 2138), passes that to the entry.js start child, and after a healthy start updates process.env.ELIZA_PORT / ELIZA_API_PORT in the shell. Why we stopped default lsof + SIGKILL: a second Eliza (or any app) on the same default port is valid when state dirs differ; killing PIDs from the shell is surprising and can terminate unrelated work. Opt-in reclaim: ELIZA_AGENT_RECLAIM_STALE_PORT=1 runs the old “free this port first” behavior for developers who want single-instance takeover.

Detached windows: when the embedded API port is finalized or changes, injectApiBase runs for the main window and all SurfaceWindowManager windows (why: chat/settings/etc. must not keep polling a stale http://127.0.0.1:…).

Related: Desktop app — Port configuration; GET /api/dev/stack overwrites api.listenPort from the accepted socket when possible (why: truth beats env if something else retargets the server).

macOS: frameless window chrome (native dylib)

On macOS, Electrobun only copies libMacWindowEffects.dylib into the dev bundle when that file exists (see packages/app/electrobun/electrobun.config.ts). Without it, traffic-light layout, drag regions, and inner-edge resize can be missing or wrong — easy to mistake for a generic Electrobun bug.

After cloning the repo, or whenever you change native/macos/window-effects.mm, build the dylib from the Electrobun package:

cd packages/app/electrobun && bun run build:native-effects

More detail: Electrobun shell package (README: macOS window chrome), and Electrobun macOS window chrome.

macOS: Local Network permission (gateway discovery)

The desktop shell uses Bonjour/mDNS to discover Eliza gateways on your LAN. macOS may show a Local Network privacy dialog — choose Allow if you rely on local discovery.

Eliza’s pinned Electrobun config types (as of the version in this repo) do not expose an Info.plist merge for NSLocalNetworkUsageDescription, so the OS may show a generic prompt. If upstream adds that hook later, we can set clearer copy; behavior does not depend on it.

Why vite build is sometimes skipped

Before starting services, the script checks viteRendererBuildNeeded() (scripts/lib/vite-renderer-dist-stale.mjs): compare packages/app/dist/index.html mtime against packages/app/src, vite.config.ts, shared packages (eliza/packages/ui, eliza/packages/app-core), etc.

Why mtime, not a full dependency graph? It is a cheap, local-first heuristic so restarts do not pay 10–30s for a redundant production build when sources did not change. Override when you need a clean bundle.

Signals, Ctrl-C, and detached children (Unix)

On macOS/Linux, long-lived children are spawned with detached: true so they live in a separate session from the orchestrator.

Why: A TTY Ctrl-C is delivered to the foreground process group. Without detached, Electrobun, Vite, and the API all receive SIGINT together. Electrobun then handles the first interrupt (“press Ctrl+C again…”) while Vite and the API keep running; the parent stays alive because stdio pipes are still open — it feels like the first Ctrl-C “did nothing.”

With detached, only the orchestrator gets TTY SIGINT; it runs a single shutdown path: SIGTERM each known subtree, short grace, then SIGKILL, then process.exit.

Second Ctrl-C while shutting down force-exits immediately (exit 1) so you are never stuck behind a grace timer.

Windows: detached is not used the same way (stdio + process model differ); port cleanup uses netstat/taskkill instead of only lsof.

Quitting from the app (Electrobun exits)

If you Quit from the native menu, Electrobun exits with code 0 while Vite and the API may still be running. The orchestrator watches the electrobun child: on exit, it stops the remaining services and exits.

Why: Otherwise the terminal session hangs after “App quitting…” because the parent process is still holding pipes to Vite/API — same underlying issue as an incomplete Ctrl-C shutdown.

Port cleanup before Vite (killUiListenPort)

Before binding the UI port, the script tries to kill whatever is already listening (why: stale Vite or a crashed run leaves EADDRINUSE). Implementation: scripts/lib/kill-ui-listen-port.mjs (Unix: lsof; Windows: netstat + taskkill).

Process trees and kill-process-tree

Shutdown uses signalSpawnedProcessTree — only the PID tree rooted at each spawned child (why: avoid pkill bun style nukes that would kill unrelated Bun workspaces on the machine).

Seeing many bun processes

Expected. You typically have: the orchestrator, bun run vite, bun --watch API, bun run dev under Electrobun (preload build + bunx electrobun dev), plus Bun/Vite/Electrobun internals. Worry if counts grow without bound or processes survive after the dev session fully exits.

IDE and agent observability (Cursor, scripts)

Editors and coding agents do not see the native Electrobun window, hear audio, or auto-discover localhost. Eliza adds explicit, machine-readable hooks so tools can still reason about “what is running” and approximate “what the user sees.”

Why this exists

1. Multi-process truth — Health is not one PID. Vite, the API, and Electrobun can disagree on ports; logs are interleaved. A single JSON endpoint and one log file avoid “grep five terminals.”
2. Security vs convenience — Screenshot and log tail endpoints are loopback-only; the screenshot path uses a session token between Electrobun and the API proxy; the log API only tails a file named desktop-dev-console.log. Why: local-first does not mean “any process on the LAN may pull your screen.”
3. Opt-out defaults — Screenshot and aggregated logging are on for dev:desktop / bun run dev because agents and humans debugging together benefit; both disable with ELIZA_DESKTOP_SCREENSHOT_SERVER=0 and ELIZA_DESKTOP_DEV_LOG=0 so you can shrink attack surface or disk I/O.
4. Cursor does not auto-poll — Discovery is documentation + .cursor/rules (see repo) plus you asking the agent to run curl or read a file. Why: the product does not silently scan your machine; hooks are there when instructed.

GET /api/dev/stack (Eliza API)

Returns stable JSON (schema: eliza.dev.stack/v1): API listen port (from the socket when available), desktop URLs/ports from env (ELIZA_RENDERER_URL, ELIZA_PORT, …), cursorScreenshot / desktopDevLog availability and paths, and short hints (e.g. Electrobun’s internal RPC port in launcher logs).

Why on the API: agents often already probe /api/health; one extra GET reuses the same host and avoids parsing Electrobun’s ephemeral port.

bun run desktop:stack-status -- --json

Script: scripts/desktop-stack-status.mjs (with scripts/lib/desktop-stack-status.mjs). Probes UI/API ports, fetches /api/dev/stack, /api/health, and /api/status.

Why a CLI: agents and CI can run it without loading the dashboard; JSON exit code reflects API health for simple automation.

Full-screen PNG — GET /api/dev/cursor-screenshot

Loopback only. Proxies Electrobun’s dev server (default 127.0.0.1:31339) which uses the same OS-level capture as ScreenCaptureManager.takeScreenshot() (e.g. macOS screencapture). Not webview-only pixels.

Why proxy through the API: one URL on the familiar API port; token stays in env between orchestrator-spawned children. Why full screen first: window-ID capture is platform-specific; this path reuses existing, tested code.

Aggregated console — file + GET /api/dev/console-log

Prefixed vite / api / electrobun lines are mirrored to .eliza/desktop-dev-console.log (session banner on each orchestrator start). GET /api/dev/console-log (loopback) returns a text tail; query maxLines (default 400, cap 5000) and maxBytes (default 256000).

Why a file: agents can read_file the path from desktopDevLog.filePath without HTTP. Why HTTP tail: avoids reading multi-megabyte logs into context; caps prevent OOM. Why basename allow-list: ELIZA_DESKTOP_DEV_LOG_PATH could otherwise be pointed at arbitrary files.

UI E2E (Playwright)

Browser smoke tests target the same renderer URL Electrobun loads in watch mode (http://localhost:<ELIZA_PORT>, default 2138). They do not drive the native Electrobun webview; tray, native menus, and packaged-only behaviors stay covered by bun run test:desktop:packaged (where applicable) and the release regression checklist.

Why Playwright: the app already ships Playwright for renderer and packaged checks, so the browser smoke flows now use the same supported stack instead of a separate TestCafe toolchain. This removes the vulnerable replicator dependency entirely and keeps the UI E2E surface on one runner.

Dependency: Playwright lives in @elizaai/app and the smoke specs live in packages/app/test/ui-smoke/. A normal root bun install still hoists workspace packages; these browser checks are opt-in via test:ui:playwright*.

Browser runtime: the suite uses Playwright Chromium. Install the browser once with cd packages/app && bunx playwright install chromium if it is not already present on the machine.

Full test matrix: bun run test does not run Playwright UI smoke by default. Set ELIZA_TEST_UI_PLAYWRIGHT=1 to append the UI suite to test/scripts/test-parallel.mjs (serial, after Vitest e2e). ELIZA_TEST_UI_TESTCAFE=1 is still accepted as a legacy alias.

Path A vs native webview (Phase B): These specs still target the renderer URL, not the embedded Electrobun webview. Packaged/native behaviors remain covered by bun run test:desktop:packaged, bun run test:desktop:playwright, and the release regression checklist.

Related source

See also

• Desktop app (Electrobun) — runtime modes, IPC, downloads
• Electrobun startup and exception handling — why main-process try/catch stays