π OpenHands: AI-Driven Development
DigitalOcean Managed Agents (MARS)
Available in the Electron desktop app and in the web build (the server hosts the bridge; see "Web build" below). A DigitalOcean agent is an immutable Agent Config (DigitalOcean's console calls it an environment); a session is a microVM launched from one, running an OpenHands agent-server with its own disk and conversations.
- Surfaces: the "Choose how you want to connect" chooser (
AddBackendChooserinbackend-form-modal.tsx) gains a third DigitalOcean tab,DigitalOceanConnectPanel: sign in (OAuth or token), then pick an OpenHands agent β opening it resumes the agent's latest live session or launches its first, and closes the modal. Each agent row expands to list its sessions as children (any connectable one opens directly), and New Agent (DigitalOceanNewAgentForm) creates an OpenHands Agent Config and launches its first session. While a MARS backend is active,MarsSessionPanel(src/components/features/sidebar/mars-session-panel.tsx) replaces the sidebar conversation list: the agent's sessions read like thread folders (the current one expands to its conversations, others open with a click), the header "+" launches a new session, and the agent menu switches agent or opensManageBackendsModal initialView="managed-agents"β the full management view insrc/components/features/backends/managed-agents/. Everything is gated ongetMarsBridge(): Electron's preload provides it, and the web build gets a fetch-backed one from the Agent Canvas server when that server hosts the MARS web bridge (below); a page with neither never shows it. - OpenHands only: agent configs are shown only when their manifest's
agentisopenhands(flatagent:orspec.agent). The list endpoint omits manifests, solistAgentConfigsinscripts/mars-tunnel-bridge.mjsfetches each config once (configs are immutable) and addsagent. The match is strict: a manifest withoutagent: openhands(older specs that no longer launch) or one that could not be read (agent: null, retried on the next list) is hidden. Sessions are shown only when theirconfig_idnames a matching config;agent_kindis not used, since OpenHands sessions reportAGENT_KIND_UNSPECIFIED. - New Agent:
createOpenHandsAgent({name, size?})inscripts/mars-tunnel-bridge.mjspostsPOST /v2/agents/configs{name, manifest_yaml}with the manifest frombuildOpenHandsManifest()(scripts/mars-api.mjs): flatagent: openhands+template: openhands+keep_warm: false, plussize:when one is chosen. No LLM key goes into the manifest; the LLM is set up in the session's agent-server (Settings β LLM) after connecting. The manifest is built in the main process, not accepted over IPC, so the renderer can only create OpenHands agents (same reasoning as pinning the guest port). Keeptemplateexplicit β harness-api has no agent kind that derives an OpenHands template. Names follow harness-api's rule (isValidAgentName: 1β64 of[A-Za-z0-9._-], alphanumeric at both ends). - Sandbox size: the New Agent form's "Sandbox size" picker lists
GET /v2/agents/sessions/sandbox/sizes(listSandboxSizes,useMarsSandboxSizes; static, sostaleTime: Infinity) and defaults to DigitalOcean's choice. The chosen slug goes into the manifest as a top-levelsize:line (slug-validated inbuildOpenHandsManifest), because sessions created from a config cannot carry a size; it therefore applies to every session of that agent. A failed or pending catalog leaves only the default and never blocks create. - Shared hooks:
useLaunchMarsSession()(open / launch / create agent / "open agent", with create-vs-connect error copy) anduseMarsSignIn()(sign-in, switch connection, sign-out) back the chooser tab, the Managed Agents view and the sidebar; reuse them instead of callingcreateSession+ connect directly. - Port-forward tunnel:
openTunnelopens the port-forward tunnel and, on desktop, returns{transport: "tunnel", host: http://127.0.0.1:<port>}; the renderer registers that host as an ordinary local backend. The public ingress URL path (direct connection toGET /v2/agents/sessions/{id}/ingress) was built and tested here and then removed from this branch on 2026-10-08 β REST worked over it but its WebSocket is reset inside the platform (microVM LB β activator, fix in microvm#1920) β and will come back once that is deployed. - Web build (browser): the server that fronts the web build (
scripts/ingress.mjsfornpm run dev,scripts/static-server.mjsfordev:staticand Docker) hosts the same bridge viascripts/mars-web-bridge.mjsand exposes it same-origin:POST /mars/rpc/<method>(an explicit allow-list of theMarsBridgesurface,RPC_METHODS;src/api/mars/mars-web-bridge.tsinstalls a fetch-backedwindow.marsBridgefromentry.client.tsxafter probingGET /mars/health), and/mars/sessions/<id>/β¦as an HTTP + WebSocket reverse proxy to the tunnel listener the server holds for that session (through the bridge's owncreateProxyHandlersinstance: no idle/response timeout, since agent-server calls can stay silent for minutes, noX-Forwarded-*, and upstream failures answer a JSON 502{error:{message}}; the tunnel client itself pings the harness socket every 30 s).openTunneltherefore answershost: <origin>/mars/sessions/<id>, a path-prefixed backend; proxied JSON has agent-server URLs (conversation_urland friends) rewritten to that prefix so the event WebSocket lands on the proxy. This is what makes the browser work at all: harness-api has no CORS, the tunnel needs a Node process, and the token must stay off the page. The routes are mounted only withMARS_WEB=1, when a key is configured or on a loopback bind (MARS_WEB=0keeps them off; both dev launchers set it on the static child so only the browser-facing ingress hosts a bridge, and Electron passesmarsWebBridge: falseso none runs there) and want the server's session key on every request: the renderer sends it asX-Session-API-Keyon/mars/rpc/*and gets anHttpOnly; SameSite=Strict; Path=/marscookie back, which the browser attaches on its own to the proxied REST calls and the WebSocket upgrade (the one request a browser cannot put a header on). The key isMARS_WEB_KEY, else the server's--session-api-key(dev-with-automationhands the stack's key toingress.mjs); with neither,mountMarsWebBridgemounts only on a loopback bind, where aHostcheck stops DNS rebinding. Onlyconversation_urlfields are rewritten (a URL inside a message is content), JSON past 8 MB streams through untouched,Cookieand the key header never reach the session host, a malformed session path is a 400, an upstream WebSocket the browser abandoned mid-handshake is terminated, anddispose()closes both ends of every proxied WebSocket. Credentials are in-memory (no keychain;MARS_TOKENseeds one at startup), OAuth is not offered (canUseOAuth: false), and cross-origin requests are refused. - Stop and delete are confirmed, destructive, and gated: Stop (
destroySession) ends the session and its sandbox throughDELETE /v2/agents/sessions/{id}, detaching any live connection first; Delete agent (deleteAgentConfig) soft-deletes the config throughDELETE /v2/agents/configs/{id}. harness-api does not refuse a delete while sessions run, so the renderer only enables it once none of the agent's sessions is live (paused counts as live). Both sit behindConfirmationModaland ride the same IPC / web-RPC surface as pause. In a session row the main action (Connect / Resume and connect / Open) is rightmost with Stop directly left of it. Removing a MARS backend in Manage Backends opensMarsBackendRemovalModalinstead of the generic confirmation: "Disconnect only" (the session keeps running and billing) or "Stop session" (destroy first, then remove; a refused destroy keeps the backend and shows the error), and Manage Backends ignores Escape / outside clicks while it is open. - One backend per session: connecting registers an ordinary
kind: "local"backend named after the session (buildMarsBackendName) whosehostis the loopback tunnel (in the web build, the server's/mars/sessions/<id>proxy), carryingmarsSessionId/marsConfigId. The backend record persists while tunnels and (in the web build) credentials do not, souseRestoreMarsTunnelsreconnects the active MARS backend once a usable DigitalOcean connection exists β after sign-in, not before β and Manage Backends keeps a MARS backend selectable while its health is red, since selecting it is what reconnects it. The far end is a real agent-server, so conversations, files, and the terminal work unmodified. Connect logic is shared throughuseConnectMarsSession()(src/hooks/use-connect-mars-session.ts), which lands the user in the session's most recent conversation (or a new chat) with the URL pinned to the new backend. - Server-side ownership: tunnels, the harness-api REST client, OAuth, and credentials live in a Node process β the Electron main process on desktop, the web server in the web build (
scripts/mars-tunnel-bridge.mjs,tunnel-client.mjs,tunnel-registry.mjs,mars-api.mjs,mars-oauth.mjs,mars-credentials.mjs) β and reach the renderer only viawindow.marsBridge(electron/preload-main.cjs, or/mars/rpc/*). harness-api sends no CORS headers and tokens must never reach the page, so do not move these calls into the renderer. - Fail fast, explain why: the tunnel records the last upstream failure (
getTunnel().upstreamFailure).waitForMarsAgentServerthrowsMarsAttachError("refused")immediately on close code 4001 or HTTP 401/403, andMarsAttachError("not-openhands")when close code 4002 (guest dial failed β nothing on :8000) outlasts a 20 s grace window, since a just-woken sandbox also closes 4002 while booting.getMarsConnectErrorMessagemaps both toDO_AGENTS$ERROR_*copy. - Cost: every probe and tunnel dial counts as sandbox activity and keeps it from auto-pausing.
useRestoreMarsTunnelsreopens only the active backend's tunnel, anduseBackendsHealthprobes non-active MARS backends once without interval/focus/reconnect refetches. Do not add background polling of sessions the user is not on. - Auth: on desktop, OAuth uses DigitalOcean's implicit grant (no client secret can ship in a desktop binary) with a fixed loopback redirect
http://127.0.0.1:53682/callback; personal access tokens always work, and are the only option in the web build. The public client ID comes fromDO_OAUTH_CLIENT_ID, elsemars.oauthClientIdinconfig/defaults.json(empty = PAT only);MARS_API_BASE_URL/mars.apiBaseUrlselect the harness API. Desktop credentials aresafeStorage-encrypted (session-only when the OS keychain is unavailable); web-build credentials are in-memory, so a server restart signs the user out. - Tests:
__tests__/components/backends/managed-agents-view.test.tsx,managed-agents-session-row.test.tsx,digitalocean-new-agent-form.test.tsx, the "DigitalOcean" blocks ofadd-backend-modal.test.tsxandmanage-backends-modal.test.tsx,__tests__/components/features/sidebar/mars-session-panel.test.tsx,__tests__/hooks/use-mars-tunnel-backend.test.tsx,__tests__/i18n/mars-session-count.test.ts, and__tests__/scripts/{mars-*,tunnel-*}.test.ts. Component tests fakewindow.marsBridge, not the hooks.