Launcher modes, Docker, desktop and library

Gotchas and known limits

• control-openhands launch covers only the full stack and --public. Partial stacks and --host need a hand-started launcher with its own HOME, OH_CANVAS_SAFE_STATE_DIR and all three OH_CANVAS_SAFE_*_PORT variables; without them it writes into the real ~/.openhands/agent-canvas and grabs the default ports 8000/18000/18001/3001 that another agent may be using.
• A hand-started launcher's first start downloads the agent-server into its private HOME cache (30–90 s). Prefix assignments are expanded left to right, so HOME=$Q/home UV_CACHE_DIR=$HOME/.cache/uv points the cache into $Q/home too, not at your real cache. Reuse one $Q for repeat launches to keep it warm.
• The browser daemon refuses other origins unless you pass --allow-external to browser goto. Each port is its own origin, so a partial-stack page starts at first run again (onboarding and a consent dialog), independent of your run's onboarding.
• In a frontend-only UI the Add a backend step's Next is enabled with an empty key, while on a LAN or --public stack it is disabled until a key is typed: the host the step probes differs (503 vs. auth-required).
• A partial-stack origin keeps its stored backend in the browser profile across launches, so a second pass lands straight in the shell. control-openhands browser reset brings back the first run on every origin; then control-openhands browser goto / and control-openhands onboard --skip restore your own run's baseline.
• Which screen a frontend-only origin shows depends on the browser, not the launcher: a profile new to the origin gets Add a backend (first run owns the initial backend), while a profile that stores a backend for that origin (the default-local entry a full launcher on the same port seeded, or any backend added there earlier) gets the recovery gate of F25.recovery-gate as soon as that backend answers 503 (F26.frontend-only-returning). The no-toast check belongs to the first-run state only: on the gate, browser toasts --history lists generic An error occurred status toasts raised by the failing 503 probes (two within 12 s here), with no hint of which request failed. Known failure (reproduced 2026-10-08): both toasts come from the free-models hydrator's GET /api/llm/models/verified 503, which no meta.disableToast guards on that screen (nor does backend-version.tsx); #18160.
• Stopping a backend-only instance while the frontend-only page that uses it stays open is the same backend-down state as F25.recovery-gate after a reload; keep the returning-user bullet above as the frontend-only-specific check (it reproduces the default-local case).
• The launcher serves the bundled VS Code editor. #17660 made that opt-in (OH_CANVAS_ENABLE_VSCODE=true) and #18048 reverted it, so only a checkout between the two needs the variable (launch --vscode sets it). A launcher that serves it reserves /vscode/: a frontend-only stack answers 503 there and logs [static] /vscode -> 503 (rejected); a stack with an agent-server lists /vscode → http://127.0.0.1:<agent-server port + 1000> in its ingress banner and hands the agent-server that editor port (19961 for the hand-started launchers here, 19000 for the desktop app), which the launcher's own port check does not cover. On a checkout between the two without the variable, /vscode/ is an ordinary SPA URL (200). Here the agent-server has no editor binary (VSCode server binary not found, VSCode will be disabled in the launcher log, /api/vscode/status {"running":false,"enabled":true}), so the editor port stays free even then.
• The port-in-use error is printed twice, the second time with a Node stack trace, and suggests PORT=<other> rather than --port (#17949). The --public key error's example says npm run dev -- --public instead of the npx command.
• A backend-only instance's /server_info.runtime_services still describes the ingress as routing /* to the frontend, which it does not run (#17949).
• The Electron app hardcodes ports 8000/18000/18001 (and the static server takes 3001), ignores PORT, and refuses to start as root without --no-sandbox (Running as root without --no-sandbox is not supported). npm run desktop first runs build:app, which rebuilds build/ under every other run: start node_modules/.bin/electron --no-sandbox electron directly against the existing build.
• Never stop the desktop app with one group-wide signal: when Xvfb dies with Electron, the app exits without stopping its backend, which is left orphaned (own process groups, parent 1) on 8000/18000/18001/3001 and blocks the next start. If that happens, find the orphans by their ports' command lines (ps -eo pid,pgid,cmd, look for --port 18000, --port 18001, --port 3001, ingress.mjs --port 8000) and stop each group by id.
• The generated session key lives in $HOME/.openhands/agent-canvas/api-key.txt, not under OH_CANVAS_SAFE_STATE_DIR: a hand-started launcher without a private HOME reads and writes the operator's real key file.
• A browser origin keeps the backends it stored on an earlier pass: after the LAN pass on 18960, a later loopback launch on 18960 shows the stale QA_LAN backend (red, old key) instead of onboarding, although the page injects a valid key. Assert key-injection bullets through the window globals, or browser reset first.
• Electron's splash shows each raw service-log line (agent-server: {"asctime": ...) as its status text during boot; the named phases only appear between them.
• build:lib from a copy whose node_modules is a symlink emits bundled dependencies under dist/<absolute node_modules path>/...; that path is an artifact of the copy, not of the product.
• **Bug candidate (F26.host-bind-lan-optin):** scripts/bind-host.mjs tells npm users to pass --allow-lan-session-key, but neither bin/agent-canvas.mjs nor scripts/dev-with-automation.mjs parses or forwards it (only scripts/static-server.mjs and the Docker entrypoint do), and unknown flags are silently ignored (#17949, whose first item is exactly this; reproduced again on 2026-10-08 at d2c89252d).
• Known issue #17946: the npm launcher never creates its TMUX_TMPDIR, so hand-started instances share one tmux server and a restart of one resets the others' terminals.