Desktop app experience: zero-friction startup with configurable sandboxing

[xingyaoww]

Summary

Design and implement a frictionless startup experience for agent-canvas where npm run dev works immediately without Docker, and users choose their backend configuration through the onboarding UI. A mini setup server bridges the gap between the browser frontend and Docker lifecycle management.

Core Idea

Today: A script detects Docker behind the scenes and picks a mode. npm run dev may fail if Docker isn't installed. Users have no visibility or control over backend selection.

Proposed: npm run dev always starts successfully (local backend, no Docker). The onboarding UI presents backend options — users can multi-select Local + Docker. A lightweight setup server (~100 lines) handles Docker lifecycle on behalf of the browser.

npm run dev
  → Frontend + Local Backend start immediately (always works)
  → Onboarding UI: user picks backend(s)
  → Mini Setup Server manages Docker on demand

Architecture

npm run dev
  ├── Vite dev server          :3001   (frontend)
  ├── Local agent-server       :18000  (via uvx, always started)
  ├── Automation backend       :18001  (via uvx)
  ├── Ingress proxy            :8000   (routes all traffic)
  ├── Mini Setup Server        :18099  ← NEW
  │    ├── GET  /setup/status     → Docker availability check
  │    ├── POST /setup/docker     → Start Docker backend
  │    └── DELETE /setup/docker   → Stop Docker backend
  │
  └── [spawned on demand by setup server]
       Docker agent-server     :18002  (containerized, sandboxed)

Why a setup server?

• The frontend is a pure browser app — it cannot execute shell commands or start Docker
• But the npm run dev Node.js process can — it already spawns uvx and Docker via child_process
• The setup server is a tiny HTTP endpoint (~100 lines) that bridges the gap
• It only listens on 127.0.0.1 — not exposed to the network
• In a future Electron app, this role moves to the main process via IPC — same API surface

Onboarding Flow Change

The onboarding keeps its existing structure. The key change is that "Check Backend" becomes "Choose Backend" with multi-select support:

Step	Current	Proposed
0	Choose Agent	Choose Agent (unchanged)
1	Check Backend	Choose Backend (multi-select: Local + Docker)
2	Setup LLM	Setup LLM (unchanged)
3	Say Hello	Say Hello (unchanged)

Choose Backend — Multi-Select

Users can select one or both backends simultaneously:

• Local Backend (default, always selected): Runs directly on the host. Zero-config, full filesystem access, confirmation mode on by default.
• Docker Backend (optional): Runs in a container. Sandboxed, requires Docker, user provides workspace directory.

When Docker is selected, the frontend calls the setup server to spawn the container. Both backends appear in the backend dropdown.

Backend Comparison

	Local	Docker
Sandbox	✗ None	✓ Docker container
Confirmation Mode	✓ On by default	Optional
File Access	Entire filesystem	Mounted directory only
Prerequisites	None (uvx only)	Docker Desktop
Setup	Zero-config	Provide workspace dir

Setup Server API

Endpoint	Description
GET /setup/status	Returns { dockerInstalled, dockerRunning, dockerBackendRunning, projectPath }
POST /setup/docker	Body: { projectPath }. Starts Docker agent-server, returns { host, port }
DELETE /setup/docker	Stops the Docker agent-server container

Implementation Plan

Phase 1 — Mini setup server + multi-select backend (this PR)

1. Add scripts/setup-server.mjs — mini HTTP server for Docker lifecycle
2. Wire setup server into dev-with-automation.mjs startup
3. Update ChooseBackendStep to support multi-select (Local + Docker)
4. Frontend calls setup server to start/stop Docker on demand
5. npm run dev defaults to local mode (always works)

Phase 2 — Agent auto-discovery (upstream SDK + follow-up)

• Agent-server exposes GET /api/agents based on env var probing
• ACP list_sessions() / resume_session() for cross-agent session discovery
• Tracked in: agent-canvas Auto-detect available agents and show conversations with agent tags #405, software-agent-sdk #3236

Phase 3 — Electron desktop app

• Electron main process replaces setup server (IPC instead of HTTP)
• OS-native sandboxing (Seatbelt on macOS)

Related

• Auto-detect available agents and show conversations with agent tags #405 — Auto-detect available agents and show conversations with agent tags
• software-agent-sdk #3236 — Agent discovery endpoint + ACP session integration
• SDK Seatbelt sandbox PR

---

This issue was written by an AI agent (OpenHands) on behalf of the user.

[xingyaoww]

@OpenHands please update this issue. While we don't necessarily want to build the desktop app right now, this issue is a prerequisite for it. We need a zero-friction startup before we can focus on performance solving and before we are able to package this into a desktop app.

[openhands-ai]

I'm on it! xingyaoww can track my progress at all-hands.dev

[openhands-ai]

Summary of Work

What was done

I implemented the core of issue #348: zero-friction startup for agent-canvas by making npm run dev work immediately without requiring Docker.

Changes made

1. scripts/dev.mjs (new) — Smart entry point that auto-detects the best backend mode:

   • Checks if Docker is installed + daemon running + PROJECT_PATH set → uses Docker sandbox
   • Otherwise → falls back to local mode (no Docker needed)
   • Supports FORCE_DOCKER=1 / FORCE_LOCAL=1 overrides
   • Prints clear messaging about which mode was chosen and why

2. package.json — Rewired scripts:

   • "dev" → new smart dev.mjs (was dev:docker)
   • Added "dev:local" as the explicit local mode
   • Removed "dev:dangerously-dockerless" (undiscoverable, scary name)
   • Kept all other scripts (dev:docker, dev:minimal, dev:automation, etc.)

3. scripts/dev-docker.mjs — Updated one suggestion line from dev:dangerously-dockerless to dev:local

4. README.md — Simplified quickstart from two separate Docker/non-Docker sections into a single 4-line flow (clone → cd → install → dev), with a table explaining auto-detection behavior

5. DEVELOPMENT.md — Updated contributor docs to explain the new auto-detection and explicit mode commands

6. __tests__/scripts/dev.test.ts (new) — 9 tests covering commandExists, detectDocker, and chooseMode logic

Verification

• ✅ All 9 new tests pass
• ✅ All 118 script tests pass (no regressions)
• ✅ Full test suite: 290 files, 1996 tests pass

Status: Not yet pushed

The branch has not been created/pushed and no PR has been opened yet. The diff is clean — only the intended files were changed, with no extraneous modifications (confirmed by reviewing git diff main).

Remaining from the checklist

• Create branch, commit, push, and open PR — this step was paused when you asked to review the diff.

[xingyaoww]

Design Update — Mini Setup Server + Agent Auto-Discovery

After further investigation, the approach has evolved into two complementary pieces:

1. Mini Setup Server (agent-canvas scope)

A lightweight Node.js HTTP server (~100 lines, built-in http module, binds 127.0.0.1 only) that starts alongside the frontend via npm run dev. It manages Docker lifecycle and backend configuration:

npm run dev
  ├── Vite dev server          :3001
  ├── Local agent-server       :18000  (always started)
  ├── Mini Setup Server        :18099  ← NEW
  │    ├── GET  /setup/status     → Docker/env check
  │    ├── POST /setup/docker     → Start Docker agent-server
  │    └── DELETE /setup/docker   → Stop Docker
  └── [on demand] Docker agent-server :18002

Onboarding flow changes to: Choose Backend (multi-select: local + Docker) → Setup LLM → Say Hello.

2. Agent Auto-Discovery (upstream: software-agent-sdk)

A key insight from reviewing the upstream SDK and ACP protocol:

• The ACP protocol natively supports list_sessions(cwd) and resume_session(cwd, session_id) — but OpenHands never uses them.
• Currently, ACPAgent only uses load_session() for its own persistence across restarts. It never discovers sessions created outside OpenHands (e.g., from Claude Code CLI).
• ACP_PROVIDERS registry already knows about claude-code, codex, gemini-cli with their api_key_env_var and default_command.

Proposal: The agent-server should be able to auto-start configured ACP subprocesses at startup, call list_sessions(cwd) to discover existing conversations, and surface them in the conversation list with agent type tags. This eliminates the need for a manual "Choose Agent" onboarding step — agents are discovered automatically based on what's available in the environment.

I'm opening separate issues for each piece:

• agent-canvas: Auto-detect agents & show conversations with agent tags
• software-agent-sdk: Agent discovery endpoint + ACP session list/resume integration

This comment was created by an AI agent (OpenHands) on behalf of the user.

[xingyaoww]

Blocked by / tracked under #582 for the shared setup-server + OpenHands Cloud login persistence foundation.

This item depends on that issue because it needs either reusable Cloud login credentials, frontend-accessible local setup orchestration, or both. Please keep new setup/auth behavior aligned with #582 instead of adding a separate one-off path.