| name | egui-app-runner |
|---|---|
| description | Use this skill when building, running, launching, or debugging an engine-first egui application across runtime targets: the native desktop app (eframe/wgpu), headless CLI and batch runner, authenticated JSON TCP control channel and MCP server, offscreen egui visual snapshots, or WebAssembly browser builds (via Trunk or Docker). Also use when configuring GPU backend fallbacks or single-instance locks. |
In a multi-crate Cargo workspace with separate binary targets (<app>, <app>-cli, <app>-web, xtask), always pass -p <package> to cargo run or cargo build to select the target binary:
<app>(apps/<app>) — native desktopeframe/egui/wgpuGUI application<app>-cli(apps/<app>-cli) — headless CLI, persistent JSON-lines server (serve), and MCP server (mcp)<app>-web(apps/<app>-web) — WebAssembly browser applicationxtask(xtask) — workspace build, test, and verification runner (cargo xtask ...)
Use --release for smooth interactive frame rates (or configure [profile.dev.package."*"] opt-level = 2 in Cargo.toml for responsive debug builds):
# Launch the desktop app
cargo run --release -p <app>
# Open one or more files directly on launch
cargo run --release -p <app> -- path/to/document.ext
# Force a separate instance if single-instance locking is enabled
cargo run --release -p <app> -- --new-instanceapps/<app>-cli drives the core engine and io crates without opening a window or requiring a display server:
# Inspect document metadata and state as JSON
cargo run --release -p <app>-cli -- info in.ext
# Execute engine commands on a document headlessly
cargo run --release -p <app>-cli -- run in.ext \
--cmd item.create --params '{"name":"Example"}' \
--out out.ext
# Search the command registry
cargo run --release -p <app>-cli -- commands --filter itemRender egui UI layouts to an image without launching a window or stealing focus:
cargo run -p <app>-ui-egui --example snapshotStart the desktop app with --control and a bearer token file, then send newline-delimited JSON-RPC requests to inspect egui state, invoke commands, simulate pointer/keyboard input, or capture screenshots:
# 1. Start the desktop app with control server enabled
cargo run --release -p <app> -- --control 7878 \
--control-token-file .private/control.token \
--automation-read-root work --automation-write-root work
# 2. Authenticate, run a command, and capture a screenshot
TOKEN=$(tr -d '\r\n' < .private/control.token)
printf '%s\n' \
"{\"id\":\"auth\",\"method\":\"auth\",\"params\":{\"token\":\"$TOKEN\"}}" \
'{"id":1,"method":"engine.execute","params":{"command":"item.create","params":{"name":"Demo"}}}' \
'{"id":2,"method":"ui.screenshot","params":{"path":"work/shot.png"}}' \
| nc 127.0.0.1 7878- Headless MCP (in-process
Session, no window):cargo run --release -p <app>-cli -- mcp \ --automation-read-root "$PWD/work" \ --automation-write-root "$PWD/work"
- Bridged MCP (live desktop
eguiUI + MCP server):- Launch the desktop app with
--control,--control-token-file, and the--automation-*-rootflags (in bridge mode, filesystem roots are configured on the desktop process; if the token file does not exist, the app creates it with a fresh 256-bit token and0600permissions):mkdir -p .private work cargo run --release -p <app> -- \ --control 7878 \ --control-token-file "$PWD/.private/control.token" \ --automation-read-root "$PWD/work" \ --automation-write-root "$PWD/work"
- Start the MCP bridge pointing at the desktop app's loopback port and token file:
cargo run --release -p <app>-cli -- mcp \ --bridge 127.0.0.1:7878 \ --control-token-file "$PWD/.private/control.token"
- For MCP client configs (
mcpServers), buildcargo build --release -p <app> -p <app>-clionce and invoke the compiledtarget/release/<app>-clibinary directly so stdio startup doesn't wait on Cargo.
- Bridge vs. Headless tool availability:
ui_*tools (ui_inspect,ui_set,ui_pointer,ui_menu_invoke,ui_screenshot) andcontrol_callwork only in bridge mode (driving the liveeguiwindow). Engine/document tools (command_run,command_list,doc_new,doc_open,doc_save,doc_inspect,jobs_list, etc.) work in both.
- Launch the desktop app with
Prerequisites: rustup target add wasm32-unknown-unknown and trunk.
# Quick check that non-desktop crates compile cleanly for wasm32
cargo xtask wasm
# Serve locally with Trunk
cd apps/<app>-web && trunk serve --releaseFor GPU startup recovery (--safe-gpu, WGPU_BACKEND), single-instance lock behavior (instance.lock), log rotation, live design token hot-reloading, and frame latency tracing, read runtime-flags-and-debugging.md.
For running test suites, egui_kittest GPU serialization (gpu_lock), real-file corpus oracles, and performance benchmarks (xtask perf), use egui-testing-infrastructure.