Launcher modes, Docker, desktop and library

Run node bin/agent-canvas.mjs --version; echo "exit=$?" and node bin/agent-canvas.mjs -v; echo "exit=$?". Each prints one line equal to jq -r .version package.json (the checkout's package version, which changes with every release: compare, do not expect a number; e.g. [ "$(node bin/agent-canvas.mjs --version)" = "$(jq -r .version package.json)" ] && echo same) and exit=0.

Run node bin/agent-canvas.mjs --info. It prints @openhands/agent-canvas <version> (the --version value), Default stack versions: with agent-server: <pin> and automation: <pin>, Compatibility: agent-server: >= <minimum>, Default ports: ingress: 8000, agent-server: 18000, automation: 18001, and the override variables OH_AGENT_SERVER_VERSION, OH_AGENT_SERVER_GIT_REF, OH_AGENT_SERVER_LOCAL_PATH / OH_AUTOMATION_VERSION, OH_AUTOMATION_GIT_REF. The three versions are read from config/defaults.json (versions.agentServer, versions.automation, compatibility.minimumAgentServer) and move with every pin bump, so compare them with the file instead of expecting numbers: test "$(node bin/agent-canvas.mjs --info | awk '/^(Default stack versions|Compatibility):/{s=1;next} /^$/{s=0} s{print $NF}' | paste -sd' ' -)" = "$(jq -r '[.versions.agentServer,.versions.automation,.compatibility.minimumAgentServer]|join(" ")' config/defaults.json)" && echo match || echo mismatch prints match, and printf '%s\n' "$(jq -r .compatibility.minimumAgentServer config/defaults.json)" "$(jq -r .versions.agentServer config/defaults.json)" | sort -VC && echo pin-meets-minimum || echo below-minimum prints pin-meets-minimum (the default Agent Server passes the UI's own version gate).

Run node bin/agent-canvas.mjs --help. It prints USAGE:, AUTH MODES: (--public ... Users must paste it when the UI loads.), OPTIONS: (-p, --port, -H, --host, --public, --frontend-only, --backend-only, -v, --version, --info, -h, --help), ENVIRONMENT VARIABLES: and EXAMPLES:, exit 0.

Run node bin/agent-canvas.mjs --frontend-only --backend-only; echo "exit=$?" → Error: --frontend-only and --backend-only cannot be used together, exit=1. Run node bin/agent-canvas.mjs --public --frontend-only; echo "exit=$?" → Error: --public cannot be used with --frontend-only, exit=1.

Run T=$(mktemp -d); env -u LOCAL_BACKEND_API_KEY HOME=$T OH_CANVAS_SAFE_STATE_DIR=$T/state timeout 60 node bin/agent-canvas.mjs --public --port 18990; echo "exit=$?"; rm -rf $T. After ✓ uvx found it prints ✗ PUBLIC MODE requires LOCAL_BACKEND_API_KEY environment variable. and exit=1. (The successful --public launch is control-openhands launch --new --public, mapped in F01.)

Never move this checkout's build/ (other runs serve it); copy the launcher instead: T=$(mktemp -d); mkdir -p $T/bin $T/config; cp bin/agent-canvas.mjs $T/bin/; cp package.json $T/; cp config/defaults.json $T/config/; node $T/bin/agent-canvas.mjs --port 18990; echo "exit=$?"; rm -rf $T. It prints Error: No build found at <T>/build, the npm install / npm run build hint and exit=1.

Point a second launcher at your run's ingress port: P=$(control-openhands status | jq -r .ports.ingress); T=$(mktemp -d); HOME=$T OH_CANVAS_SAFE_STATE_DIR=$T/state timeout 60 node bin/agent-canvas.mjs --port $P; echo "exit=$?"; rm -rf $T. It prints Cannot start: the following ports are already in use: with • ingress: port <P> and Another agent-canvas instance may already be running., then exits 1. Your run is untouched (control-openhands doctor stays ok).

Your run was started without --host. Run P=$(control-openhands status | jq -r .ports.ingress); curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:$P/ (200), then find the machine's own address portably, LAN=$(node -e 'for (const a of Object.values(require("os").networkInterfaces()).flat()) if (a.family === "IPv4" && !a.internal) { console.log(a.address); break }'); echo "LAN=$LAN", and curl -s -o /dev/null -w '%{http_code}\n' --connect-timeout 3 http://$LAN:$P/; echo "exit=$?". At that address curl prints 000 and exit=7 (connection refused). If LAN is empty the machine has no non-loopback address: record the loopback half and leave the refused-connection half not-run with that reason (it is the behavior this ID asserts, so an empty LAN is never a pass). Read-only second view, Linux form: awk -v p=$(printf '%04X' $P) 'NR>1 && $4=="0A" && $2 ~ ":"p"$" {print $2}' /proc/net/tcp prints only 0100007F:<hex port> (127.0.0.1 in /proc/net/tcp's byte order; elsewhere list the listener with the OS's socket tool, for example ss -ltn 'sport = :'$P or lsof -nP -iTCP:$P -sTCP:LISTEN, and expect 127.0.0.1:<P> only), and grep -a 'Listening on' $OH_VERIFY_RUN/private/stack.log shows the ingress banner Listening on: http://localhost:<P>/. The LAN half of F26.host-bind-lan below is the contrast: there the same curl answers 200.

Start it: Q=$OH_VERIFY_RUN/private/f26-backend; mkdir -p $Q; HOME=$Q/home OH_CANVAS_SAFE_STATE_DIR=$Q/state OH_CANVAS_SAFE_BACKEND_PORT=18961 OH_CANVAS_SAFE_AUTOMATION_PORT=18962 OH_CANVAS_SAFE_VITE_PORT=18963 LOCAL_BACKEND_API_KEY=qa-f26-backend-key OH_SECRET_KEY=qa-f26-secret DO_NOT_TRACK=1 nohup node bin/agent-canvas.mjs --backend-only --port 18960 > $Q/launcher.log 2>&1 & echo $! > $Q/pid. Wait until curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1:18960/health is 200 (30–90 s; the first start downloads the agent-server into the private HOME). Then curl -s http://127.0.0.1:18960/ prints No backend configured for this route (status 503, also for /index.html and /assets/x.js), /server_info is 200, /api/settings is 401 without a key and 200 with -H 'X-Session-API-Key: qa-f26-backend-key'. Keep it running for the next two bullets.

Start it: Q=$OH_VERIFY_RUN/private/f26-frontend; mkdir -p $Q; HOME=$Q/home OH_CANVAS_SAFE_STATE_DIR=$Q/state OH_CANVAS_SAFE_BACKEND_PORT=18971 OH_CANVAS_SAFE_AUTOMATION_PORT=18972 OH_CANVAS_SAFE_VITE_PORT=18973 DO_NOT_TRACK=1 nohup node bin/agent-canvas.mjs --frontend-only --port 18970 > $Q/launcher.log 2>&1 & echo $! > $Q/pid (ready in a few seconds). for u in / /server_info /api/settings /sockets/events/x /api/automation/v1 /vscode/; do curl -s -o /dev/null -w "%{http_code} $u\n" http://127.0.0.1:18970$u; done prints 200 / and 503 for the four backend paths and for /vscode/: the launcher serves the VS Code editor and reserves its path, and grep -a 'vscode -> 503' $Q/launcher.log prints [static] /vscode -> 503 (rejected) (see Gotchas). In the browser: control-openhands browser goto http://127.0.0.1:18970/ --allow-external, control-openhands browser value 'testid=onboarding-backend-name' (Local), control-openhands browser value 'testid=onboarding-backend-host' (http://127.0.0.1:18970, the page origin), sleep 12, control-openhands browser toasts --history ([]: no error toast) and control-openhands browser screenshot --feature F26.frontend-only --name add-backend-step (the Add a backend card).

On that page run control-openhands browser fill 'testid=onboarding-backend-name' 'QA Backend Only', control-openhands browser fill 'testid=onboarding-backend-host' 'http://127.0.0.1:18960', control-openhands browser fill 'testid=onboarding-backend-api-key' qa-f26-backend-key, control-openhands browser click 'testid=onboarding-backend-next' and control-openhands browser wait 'testid=onboarding-step-choose-agent' --timeout 20000. On a backend state that has never answered telemetry consent, the consent dialog opens on top (control-openhands browser wait 'testid=telemetry-consent-form' --timeout 10000 succeeds; it appears a second or two after the step, so an immediate browser count can still read 0; consent is stored on the backend, so a second pass with the same $Q skips it): control-openhands browser uncheck 'testid=telemetry-consent-form >> role=checkbox', control-openhands browser click 'testid=confirm-telemetry-preferences', then control-openhands browser click 'testid=onboarding-skip' and control-openhands browser wait 'testid=root-layout' --timeout 20000. After control-openhands browser reload, control-openhands browser snapshot 'testid=backend-selector' shows status "Connected" and combobox "QA Backend Only". control-openhands browser goto http://127.0.0.1:18970/settings/secrets --allow-external and control-openhands browser count 'testid=secret-item >> has-text=OPENHANDS_AUTOMATION_API_KEY' is 1 (the backend-only instance's seeded secret), and control-openhands browser network --filter 18960 --last 5 shows byOrigin with only http://127.0.0.1:18960. control-openhands browser errors --app-only has pageErrors 0.

Needs the backend-only instance. Run control-openhands browser goto /, control-openhands browser click 'testid=backend-selector', control-openhands browser click 'testid=add-backend-menu-item', control-openhands browser click 'testid=add-backend-option-agent-server' and control-openhands browser click 'testid=add-backend-location-option-remote'. control-openhands browser text 'testid=add-backend-agent-server-panel' includes Run the remote backend with --public, set a strong LOCAL_BACKEND_API_KEY, and expose it through an SSH tunnel, ngrok, or a TLS reverse proxy. Fill testid=add-backend-name with QA_Remote, testid=add-backend-host with http://127.0.0.1:18960 and testid=add-backend-api-key with qa-f26-backend-key, click testid=add-backend-submit, then control-openhands browser wait 'testid=add-backend-modal' --state detached --timeout 15000, control-openhands browser reload and control-openhands browser snapshot 'testid=backend-selector': status "Connected", combobox "QA_Remote" (the new backend becomes active). If you run this bullet without Cross-connect first, the backend-only state has not answered telemetry consent yet: the consent dialog (This preference is saved for the local backend “QA_Remote” at http://127.0.0.1:18960.) opens over the page and blocks the selector; answer it as in Cross-connect (control-openhands browser wait 'testid=telemetry-consent-form' --timeout 10000, control-openhands browser uncheck 'testid=telemetry-consent-form >> role=checkbox', control-openhands browser click 'testid=confirm-telemetry-preferences'). Switch back with control-openhands browser click 'testid=backend-selector' and control-openhands browser click 'role=option[name="Local"]', then control-openhands browser wait 'testid=backend-selector >> role=combobox[name="Local"]' --timeout 5000 (the switch applies after a short delay: a snapshot taken right after the click still reads combobox "QA_Remote": Local; after the wait it shows combobox "Local"). Clean up: backend-selector → testid=manage-backends-menu-item; control-openhands browser text 'testid=manage-backends-row-QA_Remote' reads QA_Remote, v<version>, http://127.0.0.1:18960, Connected, LOCAL, where <version> is the backend-only instance's own report, curl -s http://127.0.0.1:18960/server_info | jq -r .version (the versions.agentServer pin in config/defaults.json unless your shell exports an OH_AGENT_SERVER_* override, which a hand-started launcher inherits); it passes the UI's gate: printf '%s\n' "$(jq -r .compatibility.minimumAgentServer config/defaults.json)" "$(curl -s http://127.0.0.1:18960/server_info | jq -r .version)" | sort -VC && echo meets-minimum || echo below-minimum prints meets-minimum. Then click testid=manage-backends-remove-QA_Remote, testid=confirmation-modal >> testid=confirm-button, testid=manage-backends-done, browser reload.

On your run, control-openhands browser eval "JSON.parse(localStorage.getItem('openhands-backends')).map(b=>({id:b.id,name:b.name,host:b.host,kind:b.kind,hasKey:!!b.apiKey}))" returns exactly one entry {id: "default-local", name: "Local", host: "http://127.0.0.1:<ingress>", kind: "local", hasKey: true} (after the Remote cleanup above), and control-openhands browser eval "({key: Boolean(window.__AGENT_CANVAS_SESSION_API_KEY__), authRequired: window.__AGENT_CANVAS_AUTH_REQUIRED__ === true})" is {key: true, authRequired: false}.

Still on your run's /, control-openhands browser eval "JSON.parse(localStorage.getItem('openhands-backends'))[0].apiKey === window.__AGENT_CANVAS_SESSION_API_KEY__" is true (compare keys inside the page; never print one). Run md5sum $OH_VERIFY_RUN/private/session-key | cut -c1-12, then control-openhands restart --rotate-key (rotatedKey true: the launcher comes back injecting a new key) and the md5sum line again; the hash changed. The open page still holds the old key, so its polls get 401 until it reloads: run control-openhands browser errors --clear, then control-openhands browser reload and control-openhands browser wait 'testid=home-screen' --timeout 20000. control-openhands browser count is 1 for testid=root-layout and 0 for testid=api-key-entry-screen, testid=agent-server-onboarding-screen and testid=onboarding-modal: Home, not the key prompt public mode shows in the same state (F01.api-key-entry). Second view: control-openhands browser eval "JSON.parse(localStorage.getItem('openhands-backends')).map(b=>({id:b.id,host:b.host,keyMatchesPage:b.apiKey===window.__AGENT_CANVAS_SESSION_API_KEY__}))" is [{id: "default-local", host: "http://127.0.0.1:<ingress>", keyMatchesPage: true}] against the new page key, control-openhands browser eval "JSON.parse(localStorage.getItem('openhands-agent-server-config')).sessionApiKey === window.__AGENT_CANVAS_SESSION_API_KEY__" is true (the legacy key is overwritten too), control-openhands browser network --filter 'api/settings' --last 2 shows status 200 under recent, and control-openhands browser errors --app-only has pageErrors 0 and appErrors 0. control-openhands api GET /api/settings works with the rotated key, and control-openhands browser screenshot --feature F26.session-key-rotated --name home-after-rotation shows Home.

With both partial stacks up: curl -s "$(control-openhands status | jq -r .baseUrl)/mars/health", curl -s http://127.0.0.1:18960/mars/health and curl -s http://127.0.0.1:18970/mars/health each print {"ok":true,"authRequired":true}, while curl -s "http://127.0.0.1:$(control-openhands status | jq -r .ports.frontend)/mars/health" | head -c 15 prints <!DOCTYPE html> (the static child behind your run's ingress has no second bridge). curl -s -o /dev/null -w '%{http_code}\n' -X POST http://127.0.0.1:18960/mars/rpc/getAuthState is 401 (no key). The frontend-only page has the bridge but no key to use it: after the cross-connect, control-openhands browser eval "({marsBridge: !!window.marsBridge, key: Boolean(window.__AGENT_CANVAS_SESSION_API_KEY__)})" on http://127.0.0.1:18970/ is {marsBridge: true, key: false} (what that does to DigitalOcean sign-in is F25's F25.digitalocean-sign-in known failure).

kill -TERM $(cat $OH_VERIFY_RUN/private/f26-frontend/pid) $(cat $OH_VERIFY_RUN/private/f26-backend/pid); after about 5 s the ports 18960–18963 and 18970–18973 are free again (check as in Preconditions). Kill by the saved pid only, never by pattern.

Start a full stack on all interfaces: Q=$OH_VERIFY_RUN/private/f26-lan; mkdir -p $Q; HOME=$Q/home OH_CANVAS_SAFE_STATE_DIR=$Q/state OH_CANVAS_SAFE_BACKEND_PORT=18961 OH_CANVAS_SAFE_AUTOMATION_PORT=18962 OH_CANVAS_SAFE_VITE_PORT=18963 LOCAL_BACKEND_API_KEY=qa-f26-lan-key OH_SECRET_KEY=qa-f26-secret DO_NOT_TRACK=1 nohup node bin/agent-canvas.mjs --host 0.0.0.0 --port 18960 > $Q/launcher.log 2>&1 & echo $! > $Q/pid, and wait until curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1:18960/ is 200. grep -a 'not loopback' $Q/launcher.log shows [auth] Bind host 0.0.0.0 is not loopback — session key will not be injected into HTML and [static] WARNING: bind host 0.0.0.0 is not loopback; refusing to inject the session API key into HTML. The served page proves it: curl -s http://127.0.0.1:18960/ | grep -o '__AGENT_CANVAS_\(SESSION_API_KEY\|AUTH_REQUIRED\)__' | sort -u prints only __AGENT_CANVAS_AUTH_REQUIRED__ and curl -s http://127.0.0.1:18960/ | grep -c qa-f26-lan-key prints 0, while your loopback run's page, curl -s "$(control-openhands status | jq -r .baseUrl)/" | grep -o '__AGENT_CANVAS_\(SESSION_API_KEY\|AUTH_REQUIRED\)__' | sort -u, prints only __AGENT_CANVAS_SESSION_API_KEY__. The bind is real: with LAN from the loopback bullet, curl -s -o /dev/null -w '%{http_code}\n' --connect-timeout 3 http://$LAN:18960/ is 200 here (refused on your run, F26.loopback-bind-default; with an empty LAN this check is not-run). The browser part below expects a profile that has never visited 127.0.0.1:18960 (true in this file's order; on a repeat pass run control-openhands browser reset first and restore your run afterwards, see Gotchas). Then control-openhands browser goto http://127.0.0.1:18960/ --allow-external and control-openhands browser eval "({key: Boolean(window.__AGENT_CANVAS_SESSION_API_KEY__), authRequired: window.__AGENT_CANVAS_AUTH_REQUIRED__ === true})" → {key: false, authRequired: true}. The onboarding shows testid=onboarding-step-check-backend with control-openhands browser enabled 'testid=onboarding-backend-next' false (no key typed). control-openhands browser click 'testid=onboarding-skip' and control-openhands browser wait 'testid=api-key-entry-screen' --timeout 15000 succeed; after sleep 12, control-openhands browser toasts --history is [] (no error toast on either screen); the bridge is mounted behind the key (F26.mars-web-bridge): curl -s http://127.0.0.1:18960/mars/health is {"ok":true,"authRequired":true}, and POST /mars/rpc/getAuthState with -H 'Content-Type: application/json' -d '{"args":[]}' is 401 without and 200 with -H 'X-Session-API-Key: qa-f26-lan-key'; control-openhands browser screenshot --feature F26.host-bind-lan --name api-key-screen. Fill testid=api-key-entry-name with QA_LAN and testid=api-key-entry-api-key with qa-f26-lan-key, click testid=api-key-entry-submit; control-openhands browser wait 'testid=root-layout' --timeout 10000 succeeds. A few seconds later the telemetry consent dialog for the new QA_LAN backend opens and blocks clicks; answer it (role=button[name="Confirm preferences"]) before driving that page further. Stop it with kill -TERM $(cat $Q/pid).

Expected: the opt-in the warning names (Pass --host 127.0.0.1 (default) for local mode, or --allow-lan-session-key only if you accept LAN exposure.) makes the npm launcher inject the key again. Start the LAN stack as above with --host 0.0.0.0 --allow-lan-session-key --port 18960 (log to $Q/launcher2.log), wait for 200, then curl -s http://127.0.0.1:18960/ | grep -o '__AGENT_CANVAS_\(SESSION_API_KEY\|AUTH_REQUIRED\)__' | sort -u. Today it prints only __AGENT_CANVAS_AUTH_REQUIRED__ and the log repeats both "not loopback" warnings: the launcher ignores the flag (fail; see Gotchas). Stop it with kill -TERM $(cat $Q/pid).

With 18960–18963 free, define a helper and start a loopback stack without a key: Q=$OH_VERIFY_RUN/private/f26-keys; mkdir -p $Q; start(){ HOME=$Q/home OH_CANVAS_SAFE_STATE_DIR=$Q/state OH_CANVAS_SAFE_BACKEND_PORT=18961 OH_CANVAS_SAFE_AUTOMATION_PORT=18962 OH_CANVAS_SAFE_VITE_PORT=18963 OH_SECRET_KEY=qa-f26-secret DO_NOT_TRACK=1 "$@" > $Q/launcher.log 2>&1 & echo $! > $Q/pid; for i in $(seq 1 60); do c=$(curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1:18960/); [ "$c" = 200 ] && break; sleep 3; done; echo "code=$c"; }; start env -u LOCAL_BACKEND_API_KEY nohup node bin/agent-canvas.mjs --port 18960 (code=200). curl -s http://127.0.0.1:18960/ | grep -o '__AGENT_CANVAS_SESSION_API_KEY__[^;<]*' | md5sum prints a hash (never print the key itself); $Q/home/.openhands/agent-canvas/api-key.txt exists (64 hex characters) and curl -s -o /dev/null -w '%{http_code}' -H "X-Session-API-Key: $(cat $Q/home/.openhands/agent-canvas/api-key.txt)" http://127.0.0.1:18960/api/settings is 200. kill -TERM $(cat $Q/pid); sleep 6, run the same start ... line again in the same shell and repeat the md5sum line: the hash is identical.

Same shell, after kill -TERM $(cat $Q/pid); sleep 6: start env LOCAL_BACKEND_API_KEY=qa-f26-pin-key nohup node bin/agent-canvas.mjs --port 18960. curl -s http://127.0.0.1:18960/ | grep -o '__AGENT_CANVAS_SESSION_API_KEY__[^;<]*' prints __AGENT_CANVAS_SESSION_API_KEY__="qa-f26-pin-key"; /api/settings is 200 with -H 'X-Session-API-Key: qa-f26-pin-key' and 401 with the saved generated key. In the browser, control-openhands browser goto http://127.0.0.1:18960/ --allow-external and control-openhands browser eval "({key: window.__AGENT_CANVAS_SESSION_API_KEY__ === 'qa-f26-pin-key', authRequired: window.__AGENT_CANVAS_AUTH_REQUIRED__ === true})" → {key: true, authRequired: false}.

Same shell, after kill -TERM $(cat $Q/pid); sleep 6: start env LOCAL_BACKEND_API_KEY=qa-f26-pin-key OH_BIND_HOST=0.0.0.0 nohup node bin/agent-canvas.mjs --port 18960. grep -a 'not loopback' $Q/launcher.log shows the same [auth] and [static] warnings as --host 0.0.0.0, and curl -s http://127.0.0.1:18960/ | grep -o '__AGENT_CANVAS_\(SESSION_API_KEY\|AUTH_REQUIRED\)__' | sort -u prints only __AGENT_CANVAS_AUTH_REQUIRED__. Stop it with kill -TERM $(cat $Q/pid); after about 6 s ports 18960–18963 are free.

Same shell, after kill -TERM $(cat $Q/pid); sleep 6. Arrange a browser that onboarded on this origin against the full launcher: start env LOCAL_BACKEND_API_KEY=qa-f26-pin-key nohup node bin/agent-canvas.mjs --port 18960 (code=200), control-openhands browser reset (a fresh profile, which also forgets your run's onboarding: restore it at the end), control-openhands browser goto http://127.0.0.1:18960/ --allow-external, control-openhands browser wait 'testid=telemetry-consent-form' --timeout 15000 (this backend state has never answered consent; a second pass on the same $Q skips the form), control-openhands browser uncheck 'testid=telemetry-consent-form >> role=checkbox', control-openhands browser click 'testid=confirm-telemetry-preferences', control-openhands browser wait 'testid=onboarding-step-choose-agent' --timeout 15000, control-openhands browser click 'testid=onboarding-skip' and control-openhands browser wait 'testid=root-layout' --timeout 20000. control-openhands browser eval "JSON.parse(localStorage.getItem('openhands-backends')).map(b=>({id:b.id,name:b.name,host:b.host}))" is [{id: "default-local", name: "Local", host: "http://127.0.0.1:18960"}]. Now serve the same port without backends: kill -TERM $(cat $Q/pid); sleep 6; start nohup node bin/agent-canvas.mjs --frontend-only --port 18960 (code=200, and curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1:18960/server_info is 503). control-openhands browser goto http://127.0.0.1:18960/ --allow-external and control-openhands browser wait 'testid=agent-server-onboarding-screen' --timeout 20000 succeed: the gate of F25.recovery-gate, not onboarding. control-openhands browser count is 1 for testid=manage-backends-modal and 0 for testid=onboarding-step-check-backend, testid=first-run-onboarding-screen, testid=api-key-entry-screen, testid=root-layout, testid=close-manage-backends-modal and testid=manage-backends-done; control-openhands browser press Escape leaves the modal (count 1). control-openhands browser text 'testid=manage-backends-row-Local' reads Local, http://127.0.0.1:18960, Disconnected, HTTP request failed (503 Service Unavailable): "Service Unavailable (no backend configured for this route)" and LOCAL, and control-openhands browser testids lists manage-backends-add (Add Backend) as the way on. control-openhands browser screenshot --feature F26.frontend-only-returning --name recovery-gate. The 503 probes are expected errors in the sweep: control-openhands browser errors (without --app-only, which keeps only your run's origin) lists external:http-error rows with 503 for http://127.0.0.1:18960/server_info, /api/settings and /api/llm/models/verified, and pageErrors is 0. Stop it with kill -TERM $(cat $Q/pid); after about 6 s ports 18960–18963 are free. Restore your run: control-openhands browser goto / and control-openhands onboard --skip.

With 18960–18963 free, start a loopback launcher whose automation cannot install: Q=$OH_VERIFY_RUN/private/f26-autofail; mkdir -p $Q; HOME=$Q/home OH_CANVAS_SAFE_STATE_DIR=$Q/state OH_CANVAS_SAFE_BACKEND_PORT=18961 OH_CANVAS_SAFE_AUTOMATION_PORT=18962 OH_CANVAS_SAFE_VITE_PORT=18963 OH_AUTOMATION_VERSION=0.0.1 LOCAL_BACKEND_API_KEY=qa-f26-autofail-key OH_SECRET_KEY=qa-f26-secret DO_NOT_TRACK=1 nohup node bin/agent-canvas.mjs --port 18960 > $Q/launcher.log 2>&1 & echo $! > $Q/pid, then poll the log until Main UI appears or the pid exits. Expected (#18362): no Main UI banner, a message naming the automation startup failure, a nonzero exit and closed ports. Known failure (reproduced 2026-10-13 twice, with 0.0.1 and 0.0.0-qa-missing): the log shows [automation] ... No solution found ... and [automation] Exited with code 1 (code 2 for the unparsable version), then Main UI: http://localhost:18960/ two seconds later; kill -0 $(cat $Q/pid) succeeds, curl http://127.0.0.1:18960/ is 200 and /api/automation/health (with the key) is 502. Stop it with kill -TERM $(cat $Q/pid); the ports free within seconds. The #18299 migration failure in the issue is the same path through a different exit cause.

Run control-openhands api GET /server_info --pick runtime_services.mode (agent-canvas) and control-openhands api GET /server_info --pick runtime_services.services.automation.url_from_agent (http://localhost:<automation port>; control-openhands status prints the ports). Then control-openhands conversation start --prompt "Reply with the single word: ok" --wait --timeout 180 (prints <id>) and control-openhands conversation events <id> --grep RUNTIME_SERVICES --from-start: the SystemPromptEvent matches, with an excerpt <RUNTIME_SERVICES>\nYou are running inside an agent-canvas dev stack started .... control-openhands conversation events <id> --grep "localhost:<automation port>" --from-start shows * Automation backend: http://localhost:<port> plus its Docs: and OpenAPI: URLs.

Write qa-f26-agent.txt (outside the workspace) containing: Using the Automation backend described in your RUNTIME_SERVICES (read its OpenAPI to find the routes), create one automation named QA_rt_auto from a prompt: the prompt is "Reply with the single word: pong. Do not run any tools.", the schedule is the cron 0 9 * * *, and it is enabled. Then dispatch one run of it now. Do not change anything else. Reply with the automation id and the run id only. Run control-openhands conversation start --prompt "$(cat qa-f26-agent.txt)" --wait --timeout 400 (note <agent-id>); the reply names <automation-id> and a run id. control-openhands conversation events <agent-id> --kinds ActionEvent --from-start shows the agent's own curl calls: http://localhost:<automation port>/api/automation/openapi.json, POST …/api/automation/v1/preset/prompt and POST …/api/automation/v1/<automation-id>/dispatch, each with the X-Session-API-Key: $OPENHANDS_AUTOMATION_API_KEY header the block names. Second view in the UI: control-openhands browser goto /automations and control-openhands browser text '[data-testid^=automation-card-] >> has-text=QA_rt_auto' (QA_rt_auto, the prompt, cron, Runs 1). Open it with control-openhands browser click '[data-testid^=automation-card-] >> has-text=QA_rt_auto >> text=QA_rt_auto' --expect-url '/automations/[0-9a-f-]+'. Within about a minute, control-openhands browser text 'testid=automation-activity-log' shows the run's summary (Replied with the single word "pong" …), a cost and Successful (control-openhands browser screenshot --feature F26.runtime-services-agent-use --name agent-created-automation-run). control-openhands api GET /api/automation/v1/<automation-id> has name QA_rt_auto, trigger.schedule 0 9 * * * and enabled true. Delete it afterwards (control-openhands api DELETE /api/automation/v1/<automation-id> --write, arrange). It runs daily at 09:00 UTC otherwise.

Never build inside the shared checkout (it regenerates i18n and typegen files the other runs hash); build in a copy: L=$OH_VERIFY_RUN/private/f26-lib; mkdir -p $L; tar --exclude=./node_modules --exclude=./build --exclude=./.git --exclude=./dist -cf - . | tar -xf - -C $L; ln -s "$PWD/node_modules" $L/node_modules; (cd $L && npm run build:lib); echo "exit=$?". It ends with ✓ built in and exit=0 (about 30 s). Then (cd $L && node -e 'const p=require("./package.json"),fs=require("fs");let ok=0,miss=[];for(const[k,v]of Object.entries(p.exports))for(const f of(typeof v==="string"?[v]:Object.values(v)))fs.existsSync(f)?ok++:miss.push(k+" -> "+f);console.log(JSON.stringify({entries:Object.keys(p.exports),ok,missing:miss}))') prints 9 entries (., ./browser, ./conversation, ./files, ./settings, ./sidebar, ./terminal, ./i18n, ./package.json), ok 25 and missing []. grep -ohE 'AgentServerUIProviders|AgentServerUIRoot|CloudOrganizationBoundary|configureTelemetry|setTelemetryConsent' $L/dist/lib/index.d.ts | sort -u lists all five. Remove the copy with rm -rf $L.

On your run's home page (control-openhands browser goto /) run control-openhands browser eval "(() => { let total=0, unscoped=[]; for (const sh of document.styleSheets) { let rules; try { rules = sh.cssRules } catch { continue } const walk = (rs) => { for (const r of rs) { if (r.selectorText) { total++; if (!r.selectorText.includes('data-agent-server-ui')) unscoped.push(r.selectorText) } else if (r.cssRules) walk(r.cssRules) } }; walk(rules) } return { scopeRoots: document.querySelectorAll('[data-agent-server-ui]').length, total, unscopedCount: unscoped.length, sample: unscoped.slice(0, 12) } })()". total is in the thousands and unscopedCount is 2: only .go<hash> and .go<hash> > *, react-hot-toast's runtime classes. control-openhands browser eval "getComputedStyle(document.querySelector('[data-agent-server-ui]')).getPropertyValue('--oh-color-base').trim()" is #181818. This proves the bundle is scoped, not that a host page is unaffected (F26.lib-host-app).

If docker info cannot reach the daemon but dockerd is installed, start it (setsid dockerd); without one, record both Docker rows blocked naming the missing daemon. With a daemon, run the image with -p 127.0.0.1:8000:8000, open http://localhost:8000/canvas and expect the Add a backend step (testid=onboarding-step-check-backend, Next disabled until a key is typed); onboarding-skip leads to testid=api-key-entry-screen. With -e AGENT_CANVAS_ALLOW_LAN_SESSION_KEY=true the key is injected and first run opens on Choose your agent, under the telemetry consent dialog. npm run build:docker behind a TLS-intercepting proxy needs the proxy CA inside the build stages (without it uv pip install / pip install in the final stage fail with CERTIFICATE_VERIFY_FAILED: self-signed certificate in certificate chain), and Docker Hub may answer 429. Build a scratch copy of the Dockerfile that only adds the CA, never an edited docker/Dockerfile: after FROM node:24-slim AS frontend-build add COPY --from=ccrca ca-bundle.crt /tmp/qa-ca.crt and ENV NODE_EXTRA_CA_CERTS=/tmp/qa-ca.crt npm_config_cafile=/tmp/qa-ca.crt, after the first USER root add the same COPY and ENV SSL_CERT_FILE=/tmp/qa-ca.crt PIP_CERT=/tmp/qa-ca.crt REQUESTS_CA_BUNDLE=/tmp/qa-ca.crt UV_NATIVE_TLS=1, then docker build -f <copy> --build-context ccrca=<dir holding ca-bundle.crt> --network host --build-arg AGENT_SERVER_IMAGE=<images.agentServer>:<versions.agentServer>-python --build-arg AGENT_SERVER_VERSION=<versions.agentServer> --build-arg AUTOMATION_VERSION=<versions.automation> --build-arg VITE_BASE_PATH=/canvas -t qa-agent-canvas:target . (the pins scripts/docker-build.mjs reads from config/defaults.json; about 5 min on a warm cache). Publish it on a free port (-p 127.0.0.1:<free>:8000; 8000 and the 188xx blocks may belong to other runs). Docker Hub may answer 429 Too Many Requests for node:24-slim; in the scratch copy only, replace both FROM node:24-slim lines with FROM mirror.gcr.io/library/node:24-slim (arrange; say so in the note). Run the unmodified image with docker run -d --name <qa-name> -p 127.0.0.1:<free>:8000 qa-agent-canvas:target. On a kernel without IPv6, docker logs <qa-name> shows IPv6 is not available; binding the frontend to 0.0.0.0. and Static-server + proxy listening on http://0.0.0.0:8000/canvas/, /canvas/ answers 200 within about 25 s and docker inspect -f '{{.State.Status}}' <qa-name> is still running minutes later (#18178 fixed by #18180, verified 2026-10-13); docker exec <qa-name> ls /opt/agent-canvas lists the mars-*.mjs bridge modules (#18343). The container's generated key is docker exec <qa-name> cat /home/openhands/.openhands/agent-canvas/api-key.txt (write it to $OH_VERIFY_RUN/private/, fill with --value-file). Settings → Application (/canvas/settings/app) shows the image's Version (agent-canvas-update-card), which matches jq -r .version package.json. Remove the containers and the image afterwards (docker rm -f, docker rmi). Record F26.lib-host-app blocked naming the missing host-app example. command -v helm kubectl prints nothing here: record F26.helm-chart blocked naming the missing helm binary and cluster; with them, helm lint helm/agent-canvas and helm template qa helm/agent-canvas render the StatefulSet, Service and Ingress, and helm install follows helm/agent-canvas/README.md.

Start a private display and the app in one process group: Q=$OH_VERIFY_RUN/private/f26-desktop; mkdir -p $Q/shots; setsid nohup sh -c "echo \$\$ > $Q/pgid; Xvfb :78 -screen 0 1440x1000x24 -nolisten tcp & sleep 1; DISPLAY=:78 HOME=$Q/home OH_CANVAS_SAFE_STATE_DIR=$Q/state LOCAL_BACKEND_API_KEY=qa-f26-desktop-key OH_SECRET_KEY=qa-f26-secret DO_NOT_TRACK=1 exec node_modules/.bin/electron --no-sandbox electron" > $Q/desktop.log 2>&1 &, then capture frames: for i in $(seq 1 40); do sleep 1; DISPLAY=:78 import -window root $Q/shots/s$(printf %02d $i).png; done. Read the frames: the first seconds show the splash (logo, OpenHands Agent Canvas, AI coding agent interface, spinner, Starting backend services…, then lines such as agent-server: {"asctime": ..., the note First launch downloads Python + the OpenHands agent server. and a Show details button); a later frame shows the main window with a File Edit View Window menu and the first-run Choose your agent step under the consent dialog naming the local backend "Local" at http://localhost:8000 (about 30 s on a warm cache, minutes on the first download). While it runs, curl -s http://127.0.0.1:8000/mars/health | head -c 15 prints <!DOCTYPE html>: the desktop stack's ingress hosts no bridge (marsWebBridge: false, F26.mars-web-bridge). Copy the frames you cite into $OH_VERIFY_RUN/evidence/F26.desktop-boot-splash/ and .../F26.desktop-main-window/. Stop in two steps: kill -TERM $(cat $Q/pgid) signals only the Electron launcher (it quits and stops its backend services); after about 10 s ports 8000, 18000, 18001 and 3001 are free again. Then kill -TERM -- -$(cat $Q/pgid) ends Xvfb; ps -o pid,cmd -g $(cat $Q/pgid) lists nothing.

Not driven: record not-run (harness gap: no verb clicks inside the Electron window or observes the OS browser handoff).

With no explicit AUTOMATION_KV_SECRET, create an owned inert automation and PUT a harmless marker to /api/automation/v1/kv/qa-session-rotation?automation_id=<id> through api --write; GET must return that marker. Run restart --rotate-key and doctor, then GET again using the helper's fresh private key. Expected: rotating authentication preserves encrypted automation state. Known failure, reproduced 2026-10-12 against automation 1.19.3: the pre-rotation read is 200 and the fresh-auth read is 500 Failed to decrypt value (#18301). This uses only disposable state and does not establish the original incident's data-loss history.

Stop only the owned automation service, make a cold backup of <run>/private/automation/automations.db, and confirm its automation_git_sync_org_config already has consecutive_auth_failures. In that disposable DB only, set alembic_version.version_num to 028; restart with a bounded timeout, then open /automations. Expected: required-service startup fails explicitly or the partial schema recovers without corrupting state. Known failure, reproduced 2026-10-12 against automation 1.19.3: migration 029 reports the duplicate column and exits 3, the launcher remains alive, and Canvas shows Automations Unavailable (#18299). Restore the cold backup, restart and doctor before continuing. Never apply this fixture to an operator database.

Reserve a loopback frontend port in an owned listener and run the genuine launcher with separate free ingress/backend/automation ports. The reported default-port branch can also be observed read-only when port 3001 is already occupied; do not stop its owner. Expected: an occupied internal frontend port receives a free fallback while explicit service-port conflicts keep their existing semantics. Known failure, reproduced 2026-10-12: agent-canvas --port 18940 exits 1 with frontend: port 3001, despite the ingress override (#17546, #16226). An explicit OH_CANVAS_SAFE_VITE_PORT is a current workaround; it does not provide automatic fallback.

After a healthy private launch, identify only its required static-server PID using launcher ancestry plus its owned frontend port, then send that child SIGKILL. Open / and check the owned launcher's liveness and authenticated /api/settings. Expected: an unexpected required-service death stops the stack and reports failure. Known failure, reproduced 2026-10-12: the launcher and backend remain alive, settings returns 200, and the main UI returns 502 Bad Gateway (#16927). This live trigger is SIGKILL, not a port-race EADDRINUSE; the failing required-child exit branch is shared. Restart and doctor to restore the run.

Inspect only this run's owned static-server process for the frontend port. Read the private key in memory and retain booleans indicating whether --session-api-key is present and whether that literal key occurs in argv; never print argv or the key. Expected: other host users cannot recover the session key from command-line arguments. Known failure, reproduced 2026-10-12: both booleans are true for the owned static frontend (#16383). Docker remains a separate unavailable prerequisite here.

Through the owned ingress, send 20 sequential authenticated /api/conversations/search?limit=1 requests on one HTTP keep-alive connection, recording response statuses and the reused local socket port, then inspect only the owned ingress's warning line. Expected: one socket does not acquire one timeout listener per request. Known failure, reproduced 2026-10-12: all 20 requests are 200 on the same socket and ingress emits MaxListenersExceededWarning for 11 timeout listeners (#16839). /server_info uses a custom enrichment handler here, so it is not the generic proxy branch. Keep header values and full logs private.

Temporarily replace only an owned Agent Server with its same pinned interpreter/state on the same port; unset LOG_JSON, CI, GITHUB_ACTIONS and LOG_RICH_TRACEBACKS, and retain its PID for cleanup. Create a bare-tool conversation whose dummy LLM points at closed http://127.0.0.1:9/v1 with zero retries. Start 60 direct /alive probes concurrently with a genuine Canvas Send message; inspect the rendered connection error and final conversation status. Expected: every probe stays below 1.5 s during failure. Known failure, reproduced 2026-10-12 on Agent Server 1.54.0: the conversation ends error and one health probe stalls 2.091 s (OpenHands/software-agent-sdk#5633). This is a finite connection-error case, separate from the unprovided cyclic websocket fixture in SDK #5373. Stop that owned replacement, restore the normal launcher and doctor.