Skip to content

🙌 OpenHands: AI-Driven Development

Remove Docker dependency from dev workflow (#635)

Rohit Malhotraedb998220ae3
diff --git a/AGENTS.md b/AGENTS.md
index 40e2fd857f..13a99d55b9 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -21,15 +21,14 @@
## Runtime Services in Dev Stacks
-- When the agent-canvas dev launchers (`npm run dev:safe` / `dev:automation` / `dev:docker` / the published `agent-canvas` binary) start a stack, they set a `VITE_RUNTIME_SERVICES_INFO` env var on the frontend describing which services are running and how the agent should reach them. The frontend forwards this verbatim as `AgentContext.system_message_suffix` on every `POST /api/conversations`, so conversations land with a `<RUNTIME_SERVICES>` block appended to the system prompt.
+- When the agent-canvas dev launchers (`npm run dev` / `dev:minimal` / the published `agent-canvas` binary) start a stack, they set a `VITE_RUNTIME_SERVICES_INFO` env var on the frontend describing which services are running and how the agent should reach them. The frontend forwards this verbatim as `AgentContext.system_message_suffix` on every `POST /api/conversations`, so conversations land with a `<RUNTIME_SERVICES>` block appended to the system prompt.
- The block lists URLs **from the agent's point of view**:
- The Agent Server is always reachable as `http://localhost:<port>` from inside the sandbox — but that is _you_, not the automation backend.
- - Host-side services (ingress, Vite, automation) are reachable as `http://localhost:<port>` in dockerless modes and `http://host.docker.internal:<port>` in `dev:docker`.
+ - Host-side services (ingress, Vite, automation) are reachable as `http://localhost:<port>`.
- Agents should treat the `<RUNTIME_SERVICES>` block as authoritative: don't hardcode `localhost:8000` for "the automation server", and don't probe random ports trying to discover services. If the block says automation is not running, skip `/api/automation` calls; otherwise use the listed `url_from_agent` + `api_prefix` (default `/api/automation`) and the `X-API-Key: $OPENHANDS_AUTOMATION_API_KEY` header.
- The launcher → frontend → suffix plumbing is:
- `scripts/dev-safe.mjs::buildRuntimeServicesInfo()` — pure helper that constructs the info object.
- `scripts/dev-with-automation.mjs::buildAutomationRuntimeServicesInfo()` — wraps it with automation details; called from both Vite spawn (`startVite`) and the static build (`static-build.mjs`).
- - `scripts/dev-docker.mjs` and `bin/agent-canvas.mjs` pass `agentHostAlias: "host.docker.internal"` to `main()` because the agent-server runs in a container in those modes.
- `src/api/agent-server-adapter.ts::buildRuntimeServicesSystemSuffix()` reads `VITE_RUNTIME_SERVICES_INFO` and renders the `<RUNTIME_SERVICES>` markdown block; `createAgentFromSettings()` attaches it to `agent_context.system_message_suffix` when present.
### `VITE_RUNTIME_SERVICES_INFO` shape
@@ -38,58 +37,57 @@ The env var is a JSON string of:
```json
{
- "mode": "dev:docker",
- "agent_host_alias": "host.docker.internal",
+ "mode": "dev:automation",
"services": {
"agent_server": {
"description": "The OpenHands Agent Server this agent is running inside. ...",
- "url_from_agent": "http://localhost:8000"
+ "url_from_agent": "http://localhost:18000"
},
"ingress": {
"description": "Unified entry point. Routes /api/automation/* ...",
- "url_from_agent": "http://host.docker.internal:8000"
+ "url_from_agent": "http://localhost:8000"
},
"frontend": {
"kind": "vite",
"description": "Vite dev server hosting the agent-canvas frontend.",
- "url_from_agent": "http://host.docker.internal:3001"
+ "url_from_agent": "http://localhost:3001"
},
"automation": {
"description": "OpenHands Automations service. All routes are mounted under '/api/automation'. Authenticate with header 'X-API-Key: $OPENHANDS_AUTOMATION_API_KEY'.",
- "url_from_agent": "http://host.docker.internal:18001",
+ "url_from_agent": "http://localhost:18001",
"api_prefix": "/api/automation",
- "docs_url": "http://host.docker.internal:18001/api/automation/docs",
- "openapi_url": "http://host.docker.internal:18001/api/automation/openapi.json",
+ "docs_url": "http://localhost:18001/api/automation/docs",
+ "openapi_url": "http://localhost:18001/api/automation/openapi.json",
"auth_env_var": "OPENHANDS_AUTOMATION_API_KEY"
}
}
}
```
-All keys under `services` are optional and omitted when the corresponding service isn't running. `frontend.kind` is `"vite"` for dev launchers running the Vite dev server and `"static"` for stacks serving a pre-built `build/` directory (`dev:docker`, `dev:dangerously-dockerless`, the published `agent-canvas` binary). `services.vite` is accepted as a legacy alias for `services.frontend` by the renderer.
+All keys under `services` are optional and omitted when the corresponding service isn't running. `frontend.kind` is `"vite"` for dev launchers running the Vite dev server and `"static"` for stacks serving a pre-built `build/` directory (`dev:static`, the published `agent-canvas` binary). `services.vite` is accepted as a legacy alias for `services.frontend` by the renderer.
-### Example `<RUNTIME_SERVICES>` block (dev:docker with automation)
+### Example `<RUNTIME_SERVICES>` block (dev with automation)
```
<RUNTIME_SERVICES>
-You are running inside an agent-canvas dev stack started in 'dev:docker' mode.
+You are running inside an agent-canvas dev stack started in 'dev:automation' mode.
The following services are reachable from your sandbox. URLs are written
from your point of view (i.e., as you should curl/fetch them).
-* Agent Server (you): http://localhost:8000
+* Agent Server (you): http://localhost:18000
The OpenHands Agent Server this agent is running inside. Tool calls (terminal, file_editor, browser, etc.) execute here.
-* Ingress: http://host.docker.internal:8000
+* Ingress: http://localhost:8000
Unified entry point. Routes /api/automation/* to the automation backend, /api/* and /sockets to the agent-server, and /* to the frontend.
-* Frontend: http://host.docker.internal:3001
- Static-file server hosting the agent-canvas production build.
-* Automation backend: http://host.docker.internal:18001
+* Frontend: http://localhost:3001
+ Vite dev server hosting the agent-canvas frontend.
+* Automation backend: http://localhost:18001
OpenHands Automations service. All routes are mounted under '/api/automation'. Authenticate with header 'X-API-Key: $OPENHANDS_AUTOMATION_API_KEY'.
- Docs: http://host.docker.internal:18001/api/automation/docs
- OpenAPI: http://host.docker.internal:18001/api/automation/openapi.json
+ Docs: http://localhost:18001/api/automation/docs
+ OpenAPI: http://localhost:18001/api/automation/openapi.json
Auth: header 'X-API-Key: $OPENHANDS_AUTOMATION_API_KEY'
Trust this block over guessing: do not assume any other URLs are running.
-In particular, http://localhost:8000 inside your sandbox is the Agent Server
+In particular, http://localhost:18000 inside your sandbox is the Agent Server
you are running inside of — NOT the automation backend.
</RUNTIME_SERVICES>
```
@@ -309,7 +307,7 @@ return new ConversationClient(getAgentServerClientOptions()).someMethod(...);
- `BackendSelector`'s cloud-org switch paths should never rethrow from the dropdown `onChange` handler: unexpected non-Axios failures need a generic error toast instead of an unhandled promise rejection, and the malformed `(cloud backend, null org)` self-heal path should fall back to the bundled backend if `/switch` fails.
- `NewConversationButton` should support keyboard dismissal (`Escape`) for its inline popover, while still keeping the popover open when its modal children (`FolderBrowserModal`, `ManageWorkspacesModal`) are active.
-- README expectation: keep the first section as a concrete, chronological from-scratch quickstart for running this frontend against a real `openhands-agent-server` (clone, install prerequisites, optional `.env`, run `npm run dev:docker` or `npm run dev:dangerously-dockerless`).
+- README expectation: keep the first section as a concrete, chronological from-scratch quickstart for running this frontend against a real `openhands-agent-server` (clone, install prerequisites, optional `.env`, run `npm run dev`).
- Keep README user-focused and move contributor/developer-specific workflows (`dev:safe`, mock mode, detailed env vars/build-test notes) into `DEVELOPMENT.md`.
- `scripts/dev-safe.mjs` uses `uvx` for temporary agent-server installation — no permanent `uv tool install` needed. Environment variables (highest precedence first):
- `OH_AGENT_SERVER_LOCAL_PATH` — absolute path to a local `software-agent-sdk` checkout. Runs the local checkout via `uvx` with `--with-editable` for `openhands-sdk`/`openhands-tools`/`openhands-workspace` and `--reinstall` for `openhands-agent-server`, so SDK edits are picked up on restart. Highest precedence.
@@ -318,18 +316,13 @@ return new ConversationClient(getAgentServerClientOptions()).someMethod(...);
- `OH_SECRET_KEY` — secret key for settings encryption; uses a static default for local dev since it's needed for reading persisted encrypted values across restarts
- `SESSION_API_KEY` / `OH_SESSION_API_KEYS_0` / `VITE_SESSION_API_KEY` — session API key for agent-server authentication; auto-generated using `crypto.randomBytes(32)` if not set, passed to both agent-server (`OH_SESSION_API_KEYS_0`) and frontend (`VITE_SESSION_API_KEY`)
- Default: released PyPI version `1.22.1` for agent-server SDK libraries
-- `scripts/dev-docker.mjs` runs the agent-server inside a Docker container instead of via `uvx`, and serves a static frontend build by default for stable user/tunnel access. The required host-projects env var is `PROJECTS_PATH` and it is mounted into the container at `/projects`. Use `npm run dev:docker:dynamic` or `node scripts/dev-docker.mjs --dynamic` for the Vite dev server. The default image uses versioned release tags:
- - `DEFAULT_AGENT_SERVER_TAG` — uses format `{version}-python` (e.g., `1.22.1-python`) for reproducibility. Note: the SDK build script strips the "v" prefix from semver release tags.
- - Should stay in sync with `DEFAULT_AGENT_SERVER_VERSION` in `dev-safe.mjs` for consistency between Docker and non-Docker dev modes
- - `OH_AGENT_SERVER_GIT_REF` — override to use a git ref-based tag (e.g., `main` → `main-python`, `abc1234` → `abc1234-python`)
- - Docker images are published from https://github.com/OpenHands/software-agent-sdk via the Agent Server workflow to `ghcr.io/openhands/agent-server`
- - The container runs as the host UID/GID when Node exposes `process.getuid()` / `process.getgid()`. In the default isolated-home mode, `/home/openhands` is a writable tmpfs and persistence remains at `/home/openhands/.openhands`, so host-owned bind mounts remain writable without persisting ordinary home cache/config files.
+
- Security: `scripts/dev-safe.mjs` and `scripts/dev-with-automation.mjs` auto-generate random API keys when needed and persist the defaults so static builds, localStorage, and restarted services stay in sync:
- `SESSION_API_KEY` — 64-character hex (256-bit) for agent-server API authentication; persisted at `~/.openhands/agent-canvas/session-api-key.txt` unless overridden via env var
- `AUTOMATION_LOCAL_API_KEY` — 64-character hex for automation backend auth; persisted at `~/.openhands/agent-canvas/automation-api-key.txt` unless overridden
- `OH_SECRET_KEY` — kept as a static default because it's used for encrypting/decrypting persisted settings values and needs consistency across restarts
- `scripts/dev-safe.mjs` should fail fast if `uvx` cannot be spawned (for example missing PATH entries).
-- `npm run dev` now runs the Docker full stack with automation and a static frontend by default (via `dev:docker`). `npm run dev:dangerously-dockerless` does the same without Docker through the `dev-static.mjs` launcher. Use `npm run dev:docker:dynamic` or `npm run dev:dangerously-dockerless:dynamic` for Vite/HMR.
+- `npm run dev` runs the full local stack via `uvx` (agent-server + automation backend + Vite dev server + ingress proxy) with no Docker dependency. `npm run dev:static` does the same but serves a production build of the frontend instead of the Vite dev server.
- `scripts/dev-with-automation.mjs` runs the full stack: agent-server, automation backend (both via uvx), frontend server, and ingress proxy. It defaults to Vite when run directly, supports `--static` for an existing build, and supports `--dynamic` so wrappers that default static can opt back into Vite. Uses a standalone ingress proxy (`scripts/ingress.mjs`) to route traffic:
- `/api/automation/*` → automation backend (:18001)
- `/api/*`, `/sockets`, etc. → agent server (:18000)
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8ab0df2d7f..6c0540790c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -12,7 +12,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
### Added
- Initial npm package release of `@openhands/agent-canvas`
-- CLI entry point (`npx @openhands/agent-canvas`) to run full stack with Docker
+- CLI entry point (`npx @openhands/agent-canvas`) to run full stack locally
- Library build mode with component barrel exports
- Subpath exports for modular imports:
- `@openhands/agent-canvas/browser`
diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
index d093251ae6..a68e03de99 100644
--- a/DEVELOPMENT.md
+++ b/DEVELOPMENT.md
@@ -4,30 +4,23 @@ This document is for contributors working on `agent-canvas` itself.
## Recommended local workflow
-The README quickstart commands (`npm run dev`, `npm run dev:docker`, and
-`npm run dev:dangerously-dockerless`) serve a static frontend build by default.
-Use them for user-like local testing, remote access, and tunnels such as ngrok.
+`npm run dev` runs the full local stack (agent-server + automation backend via
+`uvx`, Vite dev server with live reload, and an ingress proxy) — all without
+Docker.
-When you are editing the Agent Canvas frontend and want Vite live reload, use a
-dynamic command explicitly:
+For a static frontend build (better for slow networks, remote access, tunnels):
```sh
-npm run dev:docker:dynamic
+npm run dev:static
```
-For a dockerless frontend/backend dev loop:
-
-```sh
-npm run dev:dangerously-dockerless:dynamic
-```
-
-The dockerless dynamic stack uses `uvx` to run a temporary `agent-server`
+The dev stack uses `uvx` to run a temporary `agent-server`
installation on `127.0.0.1:18000` and points the frontend at it. It isolates
conversation persistence by setting separate `OH_CONVERSATIONS_PATH`,
`OH_BASH_EVENTS_DIR`, and `OH_VSCODE_PORT` values under `.openhands-dev/`, and
places tmux sockets under `/tmp` (via `TMUX_TMPDIR`) to avoid filesystem-support
-issues with mounted volumes, so it does not collide with other local or
-cloud-backed OpenHands sessions.
+issues, so it does not collide with other local or cloud-backed OpenHands
+sessions.
### Environment Variables
@@ -54,17 +47,17 @@ By default, the latest released version from PyPI is used. You can override this
```sh
# Run against a local software-agent-sdk checkout.
-OH_AGENT_SERVER_LOCAL_PATH=/abs/path/to/software-agent-sdk npm run dev:docker
+OH_AGENT_SERVER_LOCAL_PATH=/abs/path/to/software-agent-sdk npm run dev
# Use a git branch or commit (takes precedence over version)
-OH_AGENT_SERVER_GIT_REF=main npm run dev:docker
-OH_AGENT_SERVER_GIT_REF=abc1234 npm run dev:docker
+OH_AGENT_SERVER_GIT_REF=main npm run dev
+OH_AGENT_SERVER_GIT_REF=abc1234 npm run dev
# Use a specific PyPI version
-OH_AGENT_SERVER_VERSION=1.18.0 npm run dev:dangerously-dockerless
+OH_AGENT_SERVER_VERSION=1.18.0 npm run dev
```
-`OH_AGENT_SERVER_LOCAL_PATH` must be an absolute path to a `software-agent-sdk` checkout containing the `openhands-agent-server`, `openhands-sdk`, `openhands-tools`, and `openhands-workspace` workspace packages. In docker mode it is bind-mounted into the container and installed editable before the server starts. In dockerless mode the agent-server itself is rebuilt from local source on each start (`uvx --reinstall`); the other workspace packages are installed editable, so their source changes take effect without a rebuild.
+`OH_AGENT_SERVER_LOCAL_PATH` must be an absolute path to a `software-agent-sdk` checkout containing the `openhands-agent-server`, `openhands-sdk`, `openhands-tools`, and `openhands-workspace` workspace packages. The agent-server itself is rebuilt from local source on each start (`uvx --reinstall`); the other workspace packages are installed editable, so their source changes take effect without a rebuild.
### Other useful overrides
diff --git a/README.md b/README.md
index a2d9022ea0..6a7308832b 100644
--- a/README.md
+++ b/README.md
@@ -53,42 +53,11 @@ code review and dependency updates, then have your personal agents running on yo
git clone https://github.com/OpenHands/agent-canvas.git
cd agent-canvas
npm install
-npm run dev:dangerously-dockerless
+npm run dev
```
Access the UI at [http://localhost:8000](http://localhost:8000). You can add additional backends directly from the UI.
-### With Docker Sandbox
-
-If you're running on your laptop, you likely want to sandbox OpenHands to limit the agent's access to your system.
-
-Watch the video on how to run this on [Mac](https://www.youtube.com/watch?v=BenkkQmmFCg) or [Windows](https://www.youtube.com/watch?v=WAxf_RRIrB8).
-
-**Prerequisites**:
-
-- Node.js 22.12.x or later
-- `npm`
-- Docker
-
-Set `$PROJECTS_PATH` to the directory on your machine where your projects live (e.g. `/path/to/your/projects`). The agent server will mount this directory so the agent can read and edit your code.
-
-```sh
-export PROJECTS_PATH=/path/to/your/projects
-git clone https://github.com/OpenHands/agent-canvas.git
-cd agent-canvas
-npm install
-npm run dev:docker
-```
-
-Windows PowerShell workaround: if `npm run dev:docker` starts the backend but `http://localhost:8000` shows **Bad Gateway** and the logs include a Vite error like `'C:\\Program' is not recognized`, start the same stack directly with Node instead. Replace the path below with your projects folder, and do not include any prompt characters or a trailing `>` in the value.
-
-```powershell
-$env:PROJECTS_PATH = "/path/to/your/projects"
-node --env-file-if-exists=.env .\scripts\dev-docker.mjs
-```
-
-Access the UI at [http://localhost:8000](http://localhost:8000).
-
# Architecture
Agent Canvas is powered by the [OpenHands Agent Server](https://github.com/OpenHands/software-agent-sdk/tree/main/openhands-agent-server/openhands/agent_server), a REST API for running multiple agents on a single machine. Each Agent Server runs on a single host/port; the Agent Canvas can connect to multiple Agent Servers and easily flip between them.
@@ -96,10 +65,8 @@ Agent Canvas is powered by the [OpenHands Agent Server](https://github.com/OpenH
You can run an Agent Server anywhere:
- Directly on your laptop (be careful!)
-- Inside a Docker container
- On a dedicated machine like a Mac Mini
- On a virtual machine in the cloud
-- Inside a Kubernetes Pod
- Inside OpenHands Cloud (our commercial offering)
The Agent Server is often paired with an [Automation Server](https://github.com/OpenHands/automation), which lets you set up agents that run on a schedule or in response to events.
diff --git a/SELF_HOSTING.md b/SELF_HOSTING.md
index 5b085a7690..0e9e8c6ac7 100644
--- a/SELF_HOSTING.md
+++ b/SELF_HOSTING.md
@@ -14,7 +14,7 @@ This guide walks through running Agent Canvas on a virtual machine (VM) so you
## Quickstart
1. **Provision a machine**: this could be a VM on AWS or DigitalOcean, or hardware like a dedicated Mac Mini
2. **Secure the machine**: make sure it's not exposed to the public internet
-3. **Run the server**: clone this repo and run `npm run dev:dangerously-dockerless`
+3. **Run the server**: clone this repo and run `npm run dev`
4. **Get a domain**: (Optional) point a domain at your machine and set up nginx+letsencrypt
5. **Connect locally**: (Optional) point your local Agent Canvas to the VM by adding a backend
@@ -40,7 +40,7 @@ flowchart LR
user -- "HTTPS / 443" --> nginx
```
-`npm run dev:dangerously-dockerless` spins up the Vite dev server, the agent
+`npm run dev` spins up the Vite dev server, the agent
server, and the automation backend, and fronts them with an ingress proxy on
`127.0.0.1:8000` that routes by path. nginx only needs to know about that
single ingress port — it doesn't talk to the three upstreams directly.
@@ -130,11 +130,11 @@ Clone this repo, install dependencies, and start the server:
git clone https://github.com/OpenHands/agent-canvas.git
cd agent-canvas
npm install
-npm run dev:dangerously-dockerless
+npm run dev
```
> [!WARNING]
-> `dev:dangerously-dockerless` runs the agent server **directly on the host**.
+> `npm run dev` runs the agent server **directly on the host**.
> The agent has full access to the machine's filesystem, environment, and
> network. That is exactly why the firewall (step 2) and the
> `SESSION_API_KEY` below are non-negotiable: they are what stop a stranger
diff --git a/__tests__/api/agent-server-adapter.test.ts b/__tests__/api/agent-server-adapter.test.ts
index 746c3e8f68..25a27af462 100644
--- a/__tests__/api/agent-server-adapter.test.ts
+++ b/__tests__/api/agent-server-adapter.test.ts
@@ -570,20 +570,20 @@ describe("buildRuntimeServicesSystemSuffix", () => {
vi.stubEnv(
"VITE_RUNTIME_SERVICES_INFO",
JSON.stringify({
- mode: "dev:docker",
- agent_host_alias: "host.docker.internal",
+ mode: "dev:automation",
+ agent_host_alias: "localhost",
services: {
agent_server: {
description: "self",
- url_from_agent: "http://localhost:8000",
+ url_from_agent: "http://localhost:18000",
},
automation: {
description: "automations",
- url_from_agent: "http://host.docker.internal:18001",
+ url_from_agent: "http://localhost:18001",
api_prefix: "/api/automation",
- docs_url: "http://host.docker.internal:18001/api/automation/docs",
+ docs_url: "http://localhost:18001/api/automation/docs",
openapi_url:
- "http://host.docker.internal:18001/api/automation/openapi.json",
+ "http://localhost:18001/api/automation/openapi.json",
auth_env_var: "OPENHANDS_AUTOMATION_API_KEY",
},
},
@@ -592,19 +592,19 @@ describe("buildRuntimeServicesSystemSuffix", () => {
const suffix = buildRuntimeServicesSystemSuffix();
expect(suffix).toBeDefined();
expect(suffix).toContain("<RUNTIME_SERVICES>");
- expect(suffix).toContain("dev:docker");
- expect(suffix).toContain("http://localhost:8000");
- expect(suffix).toContain("http://host.docker.internal:18001");
+ expect(suffix).toContain("dev:automation");
+ expect(suffix).toContain("http://localhost:18000");
+ expect(suffix).toContain("http://localhost:18001");
expect(suffix).toContain(
- "http://host.docker.internal:18001/api/automation/docs",
+ "http://localhost:18001/api/automation/docs",
);
expect(suffix).toContain("X-API-Key: $OPENHANDS_AUTOMATION_API_KEY");
expect(suffix).toContain("</RUNTIME_SERVICES>");
// The "don't guess" line should reference the actual agent-server URL
- // for this stack, not a hardcoded :8000. We pinned :8000 here but the
- // assertion specifically anchors on the URL we supplied.
+ // for this stack, not a hardcoded port. The assertion anchors on the URL
+ // we supplied above.
expect(suffix).toContain(
- "In particular, http://localhost:8000 inside your sandbox is the Agent Server",
+ "In particular, http://localhost:18000 inside your sandbox is the Agent Server",
);
});
@@ -634,19 +634,19 @@ describe("buildRuntimeServicesSystemSuffix", () => {
vi.stubEnv(
"VITE_RUNTIME_SERVICES_INFO",
JSON.stringify({
- mode: "dev:docker",
+ mode: "dev:static",
services: {
- agent_server: { url_from_agent: "http://localhost:8000" },
+ agent_server: { url_from_agent: "http://localhost:18000" },
frontend: {
kind: "static",
description: "Static-file server hosting the agent-canvas build.",
- url_from_agent: "http://host.docker.internal:3001",
+ url_from_agent: "http://localhost:3001",
},
},
}),
);
const suffix = buildRuntimeServicesSystemSuffix();
- expect(suffix).toContain("* Frontend: http://host.docker.internal:3001");
+ expect(suffix).toContain("* Frontend: http://localhost:3001");
expect(suffix).toContain("Static-file server");
// Should NOT mislabel a static-build frontend as "Vite frontend".
expect(suffix).not.toContain("Vite frontend");
@@ -710,11 +710,11 @@ describe("createAgentFromSettings runtime services suffix", () => {
vi.stubEnv(
"VITE_RUNTIME_SERVICES_INFO",
JSON.stringify({
- mode: "dev:docker",
+ mode: "dev:automation",
services: {
- agent_server: { url_from_agent: "http://localhost:8000" },
+ agent_server: { url_from_agent: "http://localhost:18000" },
automation: {
- url_from_agent: "http://host.docker.internal:18001",
+ url_from_agent: "http://localhost:18001",
},
},
}),
diff --git a/__tests__/api/mock-file-handlers.test.ts b/__tests__/api/mock-file-handlers.test.ts
index 7e10c6ed30..32afd5f541 100644
--- a/__tests__/api/mock-file-handlers.test.ts
+++ b/__tests__/api/mock-file-handlers.test.ts
@@ -27,7 +27,7 @@ describe("mock file handlers", () => {
};
expect(response.status).toBe(200);
- // In test mode shouldReturnDockerProjectMock is false, so items is empty
+ // In test mode shouldReturnProjectMock is false, so items is empty
expect(body.items).toEqual([]);
expect(body.subdirs).toEqual([]);
expect(body.next_page_id).toBeNull();
diff --git a/__tests__/bin/agent-canvas.test.ts b/__tests__/bin/agent-canvas.test.ts
index 4f0cf71e7d..15d68bf1c4 100644
--- a/__tests__/bin/agent-canvas.test.ts
+++ b/__tests__/bin/agent-canvas.test.ts
@@ -9,7 +9,7 @@ import { describe, expect, it } from "vitest";
const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), "../..");
describe("agent-canvas CLI", () => {
- it("shows PROJECTS_PATH in --help output", async () => {
+ it("shows usage info in --help output", async () => {
const child = spawn(process.execPath, ["bin/agent-canvas.mjs", "--help"], {
cwd: repoRoot,
stdio: ["ignore", "pipe", "pipe"],
@@ -29,7 +29,8 @@ describe("agent-canvas CLI", () => {
expect(code).toBe(0);
expect(stderr).toBe("");
- expect(stdout).toContain("PROJECTS_PATH");
- expect(stdout).not.toContain("PROJECT_PATH=/path/to/projects");
+ expect(stdout).toContain("@openhands/agent-canvas");
+ expect(stdout).toContain("USAGE:");
+ expect(stdout).toContain("--help");
});
});
diff --git a/__tests__/components/features/home/workspace-selection-form.test.tsx b/__tests__/components/features/home/workspace-selection-form.test.tsx
index f9f7436cc1..9a81d25c3a 100644
--- a/__tests__/components/features/home/workspace-selection-form.test.tsx
+++ b/__tests__/components/features/home/workspace-selection-form.test.tsx
@@ -107,9 +107,9 @@ describe("WorkspaceSelectionForm", () => {
mockGetHome.mockResolvedValue({ home: "/Users/me" });
useWorkspacesStore.setState({ workspaces: [], workspaceParents: [] });
// `useResolvedWorkspaces` always queries an implicit `/projects` parent
- // (the dev:docker mount point). Default it to empty so tests that don't
- // care about it don't hit a real network call. Tests that need specific
- // behavior can replace this with their own spy.
+ // in dev mode. Default it to empty so tests that don't care about it
+ // don't hit a real network call. Tests that need specific behavior can
+ // replace this with their own spy.
mockSearchSubdirectories.mockResolvedValue({
items: [],
next_page_id: null,
@@ -274,7 +274,7 @@ describe("WorkspaceSelectionForm", () => {
expect(searchSpy).toHaveBeenCalledWith("/projects");
});
- it("Add Workspace starts at the docker /projects mount and can save nested folders", async () => {
+ it("Add Workspace starts at the /projects path and can save nested folders", async () => {
mockGetHome.mockResolvedValue({
home: "/home/openhands",
favorites: [{ label: "Downloads", path: "/home/openhands/Downloads" }],
diff --git a/__tests__/package-library.test.ts b/__tests__/package-library.test.ts
index 2fb164a0f4..8c106b0e40 100644
--- a/__tests__/package-library.test.ts
+++ b/__tests__/package-library.test.ts
@@ -49,18 +49,18 @@ describe("package library metadata", () => {
});
});
- it("uses static frontend launchers for user-facing dev commands", () => {
- expect(packageJson.scripts.dev).toBe("npm run dev:docker");
- expect(packageJson.scripts["dev:dangerously-dockerless"]).toBe(
- "node --env-file-if-exists=.env scripts/dev-static.mjs",
+ it("uses local dev commands without Docker", () => {
+ expect(packageJson.scripts.dev).toBe(
+ "node --env-file-if-exists=.env scripts/dev-with-automation.mjs",
);
- expect(packageJson.scripts["dev:static"]).toBeUndefined();
- expect(packageJson.scripts["dev:docker"]).toContain(
- "scripts/dev-docker.mjs",
+ expect(packageJson.scripts["dev:static"]).toBe(
+ "node --env-file-if-exists=.env scripts/dev-static.mjs",
);
- expect(packageJson.scripts["dev:docker:dynamic"]).toContain("--dynamic");
- expect(packageJson.scripts["dev:dangerously-dockerless:dynamic"]).toBe(
- "node --env-file-if-exists=.env scripts/dev-with-automation.mjs",
+ expect(packageJson.scripts["dev:minimal"]).toBe(
+ "node --env-file-if-exists=.env scripts/dev-safe.mjs",
);
+ expect(packageJson.scripts["dev:docker"]).toBeUndefined();
+ expect(packageJson.scripts["dev:docker:dynamic"]).toBeUndefined();
+ expect(packageJson.scripts["dev:dangerously-dockerless"]).toBeUndefined();
});
});
diff --git a/__tests__/scripts/dev-docker.test.ts b/__tests__/scripts/dev-docker.test.ts
deleted file mode 100644
index fe7a8270a9..0000000000
--- a/__tests__/scripts/dev-docker.test.ts
+++ /dev/null
@@ -1,98 +0,0 @@
-// @vitest-environment node
-// These tests load `scripts/dev-docker.mjs`, which constructs file:// URLs
-// relative to its own location via `new URL("../tools", import.meta.url)`.
-// jsdom's URL constructor ignores file:// base URLs (it falls back to its
-// document base, e.g. http://localhost:3000/), breaking that resolution;
-// the Node environment has the standard WHATWG URL behavior that honors
-// the file:// base.
-import { describe, expect, it } from "vitest";
-
-import {
- CONTAINER_HOME_DIR,
- CONTAINER_OPENHANDS_DIR,
- CONTAINER_WORKSPACES_DIR,
- getDockerHomeTmpfsArgs,
- getDockerUserArgs,
- getHostDockerUserSpec,
- getProjectsPathDockerArgs,
- isDockerPermissionDenied,
-} from "../../scripts/dev-docker.mjs";
-
-describe("CONTAINER_WORKSPACES_DIR", () => {
- it("points at the dockerized agent-server's in-container persistence dir so the working_dir the GUI sends is one the container can mkdir (regression guard for the host-path leak that caused 500 on POST /api/conversations)", () => {
- expect(CONTAINER_WORKSPACES_DIR).toBe(
- "/home/openhands/.openhands/agent-canvas/workspaces",
- );
- });
-});
-
-describe("docker host user", () => {
- it("uses the current host uid/gid when the platform exposes them", () => {
- if (
- typeof process.getuid !== "function" ||
- typeof process.getgid !== "function"
- ) {
- expect(getHostDockerUserSpec()).toBeNull();
- return;
- }
-
- expect(getHostDockerUserSpec()).toBe(
- `${process.getuid()}:${process.getgid()}`,
- );
- });
-
- it("keeps docker persistence under the standard agent home", () => {
- expect(CONTAINER_HOME_DIR).toBe("/home/openhands");
- expect(CONTAINER_OPENHANDS_DIR).toBe("/home/openhands/.openhands");
- });
-
- it("adds --user when a host uid/gid is available", () => {
- expect(getDockerUserArgs("1000:1000")).toEqual(["--user", "1000:1000"]);
- expect(getDockerUserArgs(null)).toEqual([]);
- });
-
- it("mounts a writable, executable tmpfs home for the mapped host user", () => {
- // `exec` is critical: docker's --tmpfs default is rw,noexec,nosuid,nodev,
- // which breaks stdio MCP servers that exec binaries cached under ~/.npm
- // (e.g. `npx -y @modelcontextprotocol/server-github`). We keep `nosuid`
- // and `nodev` as defense-in-depth -- $HOME has no business hosting
- // setuid binaries or device nodes -- but the `noexec` default has to go.
- expect(getDockerHomeTmpfsArgs("1000:1000")).toEqual([
- "--tmpfs",
- "/home/openhands:exec,nosuid,nodev,uid=1000,gid=1000,mode=700",
- ]);
- expect(getDockerHomeTmpfsArgs(null)).toEqual([]);
- });
-});
-
-describe("getProjectsPathDockerArgs", () => {
- it("uses PROJECTS_PATH for the /projects bind mount", () => {
- expect(
- getProjectsPathDockerArgs({ PROJECTS_PATH: "/host/projects" }),
- ).toEqual(["-v", "/host/projects:/projects"]);
- });
-
- it("does not read the old PROJECT_PATH name", () => {
- expect(getProjectsPathDockerArgs({ PROJECT_PATH: "/host/projects" })).toEqual(
- [],
- );
- });
-});
-
-describe("isDockerPermissionDenied", () => {
- it("detects Linux docker socket permission failures", () => {
- expect(
- isDockerPermissionDenied(
- "permission denied while trying to connect to the docker API at unix:///var/run/docker.sock",
- ),
- ).toBe(true);
- });
-
- it("does not treat a missing daemon as a permission failure", () => {
- expect(
- isDockerPermissionDenied(
- "failed to connect to the docker API at unix:///var/run/docker.sock; check if the path is correct and if the daemon is running",
- ),
- ).toBe(false);
- });
-});
diff --git a/__tests__/scripts/dev-safe.test.ts b/__tests__/scripts/dev-safe.test.ts
index 2ac9101132..f78b44fd58 100644
--- a/__tests__/scripts/dev-safe.test.ts
+++ b/__tests__/scripts/dev-safe.test.ts
@@ -561,7 +561,7 @@ describe("buildSafeDevConfig", () => {
expect(readFileSync(keyPath, "utf8").trim()).toBe(config.sessionApiKey);
});
- it("reuses the same key across config builds, simulating dev:docker / dev:dangerously-dockerless restarts", () => {
+ it("reuses the same key across config builds, simulating restarts", () => {
const keyPath = tempKeyPath();
const first = buildSafeDevConfig("/workspace/project/agent-canvas", {
@@ -810,10 +810,10 @@ describe("buildRuntimeServicesInfo", () => {
});
});
- it("uses host.docker.internal as the agent host alias in docker mode", () => {
+ it("supports a custom agent host alias for remote setups", () => {
const info = buildRuntimeServicesInfo({
- mode: "dev:docker",
- agentHostAlias: "host.docker.internal",
+ mode: "custom",
+ agentHostAlias: "custom-host",
agentServerPort: 8000,
ingressPort: 8000,
frontendPort: 3001,
@@ -824,19 +824,19 @@ describe("buildRuntimeServicesInfo", () => {
expect(info.services.agent_server?.url_from_agent).toBe(
"http://localhost:8000",
);
- // Host-side services use the docker alias.
+ // Host-side services use the custom alias.
expect(info.services.ingress?.url_from_agent).toBe(
- "http://host.docker.internal:8000",
+ "http://custom-host:8000",
);
expect(info.services.frontend?.url_from_agent).toBe(
- "http://host.docker.internal:3001",
+ "http://custom-host:3001",
);
// Static-mode description, not "Vite dev server".
expect(info.services.frontend?.kind).toBe("static");
expect(info.services.frontend?.description).toMatch(/Static-file server/i);
expect(info.services.frontend?.description).not.toMatch(/Vite/i);
expect(info.services.automation?.url_from_agent).toBe(
- "http://host.docker.internal:18001",
+ "http://custom-host:18001",
);
});
diff --git a/__tests__/scripts/dev-with-automation.test.ts b/__tests__/scripts/dev-with-automation.test.ts
index c60e77bb99..01ab69dd9c 100644
--- a/__tests__/scripts/dev-with-automation.test.ts
+++ b/__tests__/scripts/dev-with-automation.test.ts
@@ -325,7 +325,7 @@ describe("buildConfig", () => {
expect(config.sessionApiKey).toMatch(/^[0-9a-f]{64}$/);
});
- it("reuses the persisted session API key across calls (parity for dev:docker and dev:dangerously-dockerless restarts)", async () => {
+ it("reuses the persisted session API key across calls (stable across restarts)", async () => {
const env = envWithIsolatedKeyPath();
const first = await buildConfig({}, env);
diff --git a/bin/agent-canvas.mjs b/bin/agent-canvas.mjs
index 12cd122f40..4b74d74fa7 100755
--- a/bin/agent-canvas.mjs
+++ b/bin/agent-canvas.mjs
@@ -2,10 +2,10 @@
/**
* CLI entry point for @openhands/agent-canvas
*
- * Runs the full Agent Canvas stack using Docker for the agent-server:
- * - Agent-server runs in Docker container
+ * Runs the full Agent Canvas stack locally:
+ * - Agent-server via uvx
* - Automation backend via uvx
- * - Pre-built static frontend (not Vite dev server)
+ * - Pre-built static frontend
*
* This is the production equivalent of `npm run dev` - it runs the full stack
* but serves pre-built static assets instead of the Vite dev server.
@@ -23,42 +23,36 @@ const BUILD_DIR = join(__dirname, "..", "build");
const args = process.argv.slice(2);
if (args.includes("-h") || args.includes("--help")) {
console.log(`
-@openhands/agent-canvas - Run the Agent Canvas UI with agent-server (Docker)
+@openhands/agent-canvas - Run the Agent Canvas UI with agent-server
-Runs the full stack with agent-server in Docker, automation backend via uvx,
+Runs the full stack with agent-server and automation backend via uvx,
and serves pre-built static frontend assets.
USAGE:
npx @openhands/agent-canvas [options]
-REQUIRED:
- PROJECTS_PATH Path to your projects directory (mounted into container)
-
OPTIONS:
-p, --port <port> Ingress port (default: 8000)
-h, --help Show this help message
ENVIRONMENT VARIABLES:
- PROJECTS_PATH Required: path to your projects directory
OH_SECRET_KEY Secret key for encrypting settings
- OH_AGENT_SERVER_GIT_REF Git ref for agent-server Docker image tag
+ OH_AGENT_SERVER_GIT_REF Git ref for agent-server
OH_AGENT_SERVER_LOCAL_PATH Path to local SDK checkout (for development)
- OH_MOUNT_HOST_HOME Set to "1" to mount entire home directory
+ OH_AGENT_SERVER_VERSION Specific PyPI version for agent-server
Note: LLM settings are configured through the web UI settings page,
not environment variables.
EXAMPLES:
- # Start full stack (requires PROJECTS_PATH)
- PROJECTS_PATH=/path/to/projects npx @openhands/agent-canvas
+ # Start full stack
+ npx @openhands/agent-canvas
# Use a specific port
- PROJECTS_PATH=/path/to/projects npx @openhands/agent-canvas --port 3000
+ npx @openhands/agent-canvas --port 3000
# Use local SDK checkout for development
- PROJECTS_PATH=/path/to/projects OH_AGENT_SERVER_LOCAL_PATH=/path/to/sdk npx @openhands/agent-canvas
-
-For more options, see: node scripts/dev-docker.mjs --help
+ OH_AGENT_SERVER_LOCAL_PATH=/path/to/sdk npx @openhands/agent-canvas
`);
process.exit(0);
}
@@ -77,12 +71,9 @@ this is a packaging error. If running from source:
process.exit(1);
}
-// Import dev-docker's dependencies and run with static mode
-let main, checkDockerPrereqs, startAgentServerDocker, CONTAINER_WORKSPACES_DIR;
+let main;
try {
({ main } = await import("../scripts/dev-with-automation.mjs"));
- ({ checkDockerPrereqs, startAgentServerDocker, CONTAINER_WORKSPACES_DIR } =
- await import("../scripts/dev-docker.mjs"));
} catch (err) {
console.error("Failed to load required scripts. Try reinstalling:");
console.error(" npm install -g @openhands/agent-canvas@latest");
@@ -92,14 +83,8 @@ try {
main({
bannerTitle: "Agent Canvas",
- extraPrereqs: checkDockerPrereqs,
- startAgentServer: startAgentServerDocker,
- viteWorkingDir: CONTAINER_WORKSPACES_DIR,
staticMode: true,
staticDir: BUILD_DIR,
- // Agent-server runs in a Docker container; host services are reached
- // via "host.docker.internal" from the agent's POV.
- agentHostAlias: "host.docker.internal",
mode: "agent-canvas",
}).catch((err) => {
console.error(`Fatal error: ${err.message}`);
diff --git a/package.json b/package.json
index e78b65b195..58dacf5b88 100644
--- a/package.json
+++ b/package.json
@@ -68,14 +68,9 @@
"zustand": "5.0.12"
},
"scripts": {
- "dev": "npm run dev:docker",
- "dev:dangerously-dockerless": "node --env-file-if-exists=.env scripts/dev-static.mjs",
- "dev:dangerously-dockerless:dynamic": "node --env-file-if-exists=.env scripts/dev-with-automation.mjs",
- "dev:safe": "node --env-file-if-exists=.env scripts/dev-safe.mjs",
+ "dev": "node --env-file-if-exists=.env scripts/dev-with-automation.mjs",
+ "dev:static": "node --env-file-if-exists=.env scripts/dev-static.mjs",
"dev:extra-backend": "node --env-file-if-exists=.env scripts/dev-extra-backend.mjs",
- "dev:automation": "node --env-file-if-exists=.env scripts/dev-with-automation.mjs",
- "dev:docker": "node --env-file-if-exists=.env scripts/dev-docker.mjs",
- "dev:docker:dynamic": "node --env-file-if-exists=.env scripts/dev-docker.mjs --dynamic",
"dev:minimal": "node --env-file-if-exists=.env scripts/dev-safe.mjs",
"dev:frontend": "npm run make-i18n && cross-env VITE_MOCK_API=false react-router dev",
"dev:mock": "npm run make-i18n && cross-env VITE_MOCK_API=true react-router dev",
diff --git a/scripts/dev-docker.mjs b/scripts/dev-docker.mjs
deleted file mode 100644
index 610be019fe..0000000000
--- a/scripts/dev-docker.mjs
+++ /dev/null
@@ -1,487 +0,0 @@
-/**
- * Dockerized Development Stack
- *
- * Same as `dev-with-automation.mjs`, but runs the agent-server inside a Docker
- * container instead of via `uvx`. The default frontend is a static production
- * build for stability over tunnels and slow networks; pass `--dynamic` for the
- * Vite dev server with live reload.
- *
- * The agent-server image listens on port 8000 inside the container; we map
- * it to the host's `agentServerPort` (default 18000) so the ingress proxy
- * and the secret-seeding step can reach it via http://localhost:18000.
- *
- * Required environment variables:
- * - PROJECTS_PATH: Absolute host path to your projects. Mounted into the
- * container at /projects so the agent can read/edit your code. The
- * frontend always treats /projects as a "workspace parent", so the
- * dropdown lists its immediate subdirectories as workspaces.
- *
- * Optional environment variables:
- * - OH_AGENT_SERVER_GIT_REF: Git ref (branch/tag/SHA) of the agent-server
- * to use. Translates to the docker tag `${ref}-python`, e.g.
- * `main` -> `ghcr.io/openhands/agent-server:main-python`.
- * - OH_AGENT_SERVER_LOCAL_PATH: Absolute host path to a software-agent-sdk
- * checkout. When set, mounts the checkout at /agent-server-src inside the
- * container and reinstalls the four workspace packages
- * (openhands-{sdk,tools,workspace,agent-server}) as editable installs on
- * top of the image's pre-built venv before starting the server. Source
- * edits on the host are reflected in the running container on module
- * reload / process restart, matching the non-Docker dev loop.
- *
- * Optional credential mounts (only mounted when the host path exists):
- * - ~/.openhands -> /home/openhands/.openhands (persistence)
- * - ~/.claude -> /home/openhands/.claude (Claude credentials)
- * - ~/.codex -> /home/openhands/.codex (Codex credentials)
- * - ~/.ssh -> /home/openhands/.ssh (git/ssh access)
- *
- * Optional host home mount (opt-in):
- * Set `OH_MOUNT_HOST_HOME=1` to bind-mount your entire host home onto
- * the container user's home at `/home/openhands`. This lets the
- * "Add Workspace" file browser navigate your real host filesystem
- * (and credentials/persistence dirs above are picked up automatically
- * as subpaths). Off by default so the container stays isolated from
- * the host home unless you opt in.
- *
- * Usage:
- * PROJECTS_PATH=/path/to/your/projects npm run dev:docker
- * PROJECTS_PATH=/path/to/your/projects npm run dev:docker -- --dynamic
- * OH_AGENT_SERVER_GIT_REF=main PROJECTS_PATH=... npm run dev:docker
- */
-
-import { spawnSync } from "node:child_process";
-import { existsSync } from "node:fs";
-import { homedir } from "node:os";
-import { join } from "node:path";
-import { fileURLToPath, pathToFileURL } from "node:url";
-import process from "node:process";
-
-import {
- buildAgentServerAutomationEnv,
- c,
- commandExists,
- logError,
- logService,
- logSuccess,
- main,
- registerShutdownHook,
- spawnService,
-} from "./dev-with-automation.mjs";
-import { validateLocalAgentServerPath } from "./dev-safe.mjs";
-import { buildFrontend } from "./static-build.mjs";
-
-// Path inside the container where OH_AGENT_SERVER_LOCAL_PATH is bind-mounted.
-const CONTAINER_LOCAL_SDK_DIR = "/agent-server-src";
-
-// Host directory containing Agent-Canvas-specific Python tools (e.g. the
-// canvas_ui tool). Mounted read-only into the container and added to
-// sys.path via OH_EXTRA_PYTHON_PATH so the agent-server can import the
-// modules listed in `tool_module_qualnames`.
-const CONTAINER_CANVAS_TOOLS_DIR = "/canvas-tools";
-const HOST_CANVAS_TOOLS_DIR = fileURLToPath(
- new URL("../tools", import.meta.url),
-);
-
-// Docker image for the agent-server.
-const AGENT_SERVER_REPO = "ghcr.io/openhands/agent-server";
-// Default tag used when OH_AGENT_SERVER_GIT_REF is not set.
-// Should match DEFAULT_AGENT_SERVER_VERSION in dev-safe.mjs for consistency.
-// Format: {version}-python (e.g., 1.22.1-python) for released versions.
-// Note: The SDK build script strips the "v" prefix from semver release tags.
-const DEFAULT_AGENT_SERVER_TAG = "1.22.1-python";
-const CONTAINER_NAME = "agent-canvas-dev-agent-server";
-
-// Keep the in-container home at the path advertised by the agent-server
-// image. The default isolated-home launch overlays this path with tmpfs
-// before mounting ~/.openhands below it, so OH_PERSISTENCE_DIR can stay at
-// the conventional $HOME/.openhands instead of inventing a second home root.
-const CONTAINER_HOME_DIR = "/home/openhands";
-const CONTAINER_OPENHANDS_DIR = `${CONTAINER_HOME_DIR}/.openhands`;
-
-// Default secret key matches dev-safe.mjs so persisted settings stay
-// decryptable across docker / non-docker runs.
-const DEFAULT_SECRET_KEY = "openhands-dev-secret-key-change-in-prod";
-
-// Path inside the container where the agent-server stores per-conversation
-// workspace directories. Mirrors dev-with-automation.mjs's host-side
-// `${stateDir}/workspaces`, but rooted under the container's persistence
-// dir (which is `~/.openhands` on the host, mounted in below). The frontend
-// receives this via VITE_WORKING_DIR so the working_dir it sends to the
-// agent-server is one the container can actually mkdir.
-const CONTAINER_WORKSPACES_DIR = `${CONTAINER_OPENHANDS_DIR}/agent-canvas/workspaces`;
-
-/**
- * Resolve the docker image to use based on environment.
- *
- * If OH_AGENT_SERVER_GIT_REF is set, use `${ref}-python` as the tag, mirroring
- * the publishing convention (e.g. `main` -> `main-python`, `abc1234` ->
- * `abc1234-python`). Otherwise fall back to the pinned default tag.
- */
-function resolveAgentServerImage(env = process.env) {
- const gitRef = env.OH_AGENT_SERVER_GIT_REF;
- const tag = gitRef ? `${gitRef}-python` : DEFAULT_AGENT_SERVER_TAG;
- return `${AGENT_SERVER_REPO}:${tag}`;
-}
-
-function suggestDockerless() {
- logError("");
- logError(
- "If you'd rather not use Docker, you can run the agent-server directly with:",
- );
- logError(" npm run dev:dangerously-dockerless");
- logError("Note: this runs the agent with full access to your filesystem.");
-}
-
-function isDockerPermissionDenied(stderr) {
- const normalized = stderr.toLowerCase();
- return (
- normalized.includes("permission denied") &&
- (normalized.includes("docker.sock") ||
- normalized.includes("docker api") ||
- normalized.includes("/var/run/docker") ||
- normalized.includes("/run/docker"))
- );
-}
-
-function logDockerInfoFailure(stderr) {
- if (isDockerPermissionDenied(stderr)) {
- logError(
- "docker is installed and the daemon may be running, but this user cannot access the Docker API.",
- );
- if (stderr) {
- logError(` ${stderr.split("\n")[0]}`);
- }
- logError(
- "On Linux, add your user to the docker group, then log out and back in:",
- );
- logError(" sudo usermod -aG docker $USER");
- logError("Verify with: docker info");
- return;
- }
-
- logError("docker is installed but the daemon does not appear to be running.");
- if (stderr) {
- logError(` ${stderr.split("\n")[0]}`);
- }
- logError("Start Docker (e.g. open Docker Desktop) and try again.");
-}
-
-function getHostDockerUserSpec() {
- if (
- typeof process.getuid !== "function" ||
- typeof process.getgid !== "function"
- ) {
- return null;
- }
- return `${process.getuid()}:${process.getgid()}`;
-}
-
-function getDockerUserArgs(userSpec = getHostDockerUserSpec()) {
- return userSpec ? ["--user", userSpec] : [];
-}
-
-/**
- * When `docker run --user <host uid>:<host gid>` is set, the process no
- * longer runs as the image's `openhands` user. The image home directory is
- * owned by that image user and has mode 0700, so the mapped host user cannot
- * enter `/home/openhands` unless we replace or mutate it.
- *
- * We deliberately use a tmpfs overlay instead of:
- * - chown/chmod: would require starting the container as root and adding a
- * wrapper just to repair the image home before dropping privileges.
- * - a custom home path: would make OH_PERSISTENCE_DIR stop looking like the
- * normal $HOME/.openhands location and make future path reasoning harder.
- *
- * Cache/config writes that libraries place under $HOME stay ephemeral in this
- * tmpfs. The only persisted default-home state is the explicit
- * ~/.openhands -> /home/openhands/.openhands bind mount below.
- *
- * We explicitly pass `exec` because docker's `--tmpfs` default option set is
- * `rw,noexec,nosuid,nodev`. `noexec` breaks any agent flow that needs to run a
- * binary out of `$HOME` -- most visibly stdio MCP servers installed via
- * `npx -y @modelcontextprotocol/server-*`, which cache their executables under
- * `~/.npm/_npx/...` and then exec them. With the default `noexec` flag, those
- * execs fail with "Permission denied" regardless of the file mode bits, and
- * the failure only surfaces when a conversation tries to spin the MCP server
- * up -- aborting agent initialization with a confusing traceback.
- *
- * `nosuid` and `nodev` are preserved (the home dir has no business hosting
- * setuid binaries or device nodes); only the `noexec` default is overridden.
- */
-function getDockerHomeTmpfsArgs(userSpec = getHostDockerUserSpec()) {
- if (!userSpec) {
- return [];
- }
-
- const [uid, gid] = userSpec.split(":");
- if (!uid || !gid) {
- return [];
- }
-
- return [
- "--tmpfs",
- `${CONTAINER_HOME_DIR}:exec,nosuid,nodev,uid=${uid},gid=${gid},mode=700`,
- ];
-}
-
-/**
- * Check that the docker CLI is on PATH AND that the docker daemon is
- * actually responding. `commandExists("docker")` only verifies the binary is
- * installed, which is not enough -- on macOS / Windows the daemon may be
- * stopped, and on Linux the user may not have permissions to talk to it.
- */
-function getProjectsPathDockerArgs(env = process.env) {
- return env.PROJECTS_PATH ? ["-v", `${env.PROJECTS_PATH}:/projects`] : [];
-}
-
-function checkDockerPrereqs(config) {
- if (!commandExists("docker")) {
- logError("docker is required for dev:docker but was not found on PATH.");
- logError("Install Docker: https://docs.docker.com/get-docker/");
- suggestDockerless();
- process.exit(1);
- }
- logSuccess("docker found");
-
- // `docker info` exits non-zero (and writes to stderr) if the daemon
- // isn't reachable. Use a short timeout to avoid hanging.
- const info = spawnSync("docker", ["info"], {
- stdio: ["ignore", "ignore", "pipe"],
- timeout: 10_000,
- });
- if (info.status !== 0) {
- const stderr = info.stderr ? info.stderr.toString().trim() : "";
- logDockerInfoFailure(stderr);
- suggestDockerless();
- process.exit(1);
- }
- logSuccess("docker daemon is running");
-
- if (!process.env.PROJECTS_PATH) {
- logError("PROJECTS_PATH is required for dev:docker.");
- logError("Set it to the directory containing your projects, e.g.:");
- logError(" export PROJECTS_PATH=/path/to/your/projects");
- process.exit(1);
- }
- logSuccess(`PROJECTS_PATH=${process.env.PROJECTS_PATH}`);
-}
-
-function startAgentServerDocker(config) {
- const image = resolveAgentServerImage();
- const localSdkPath = process.env.OH_AGENT_SERVER_LOCAL_PATH;
-
- // Validate up-front so we fail fast before touching docker if the user
- // pointed at a missing / incomplete checkout.
- if (localSdkPath) {
- validateLocalAgentServerPath(localSdkPath);
- }
-
- logService(
- "agent-server",
- `Starting in Docker on port ${config.agentServerPort} (image: ${image})...`,
- c.blue,
- );
- if (localSdkPath) {
- logService(
- "agent-server",
- `Using local SDK source: ${localSdkPath} (mounted at ${CONTAINER_LOCAL_SDK_DIR})`,
- c.blue,
- );
- }
-
- // Best-effort cleanup of any leftover container from a previous run.
- spawnSync("docker", ["rm", "-f", CONTAINER_NAME], { stdio: "ignore" });
- registerShutdownHook(() => {
- spawnSync("docker", ["rm", "-f", CONTAINER_NAME], { stdio: "ignore" });
- });
-
- const home = homedir();
- const userSpec = getHostDockerUserSpec();
- const dockerArgs = ["run", "--rm", "--name", CONTAINER_NAME, "--init"];
- dockerArgs.push(...getDockerUserArgs(userSpec));
- dockerArgs.push(...getProjectsPathDockerArgs());
- // Read-only mount of the Agent-Canvas tools directory. Coupled with
- // OH_EXTRA_PYTHON_PATH below so the agent-server can import
- // canvas_ui_tool when the conversation request lists it under
- // tool_module_qualnames.
- dockerArgs.push(
- "-v",
- `${HOST_CANVAS_TOOLS_DIR}:${CONTAINER_CANVAS_TOOLS_DIR}:ro`,
- );
-
- // Bind-mount the local software-agent-sdk checkout if requested. Mounted
- // rw so editable installs can write their .dist-info into each package
- // (matches the side effect of the non-Docker uvx --with-editable path).
- if (localSdkPath) {
- dockerArgs.push("-v", `${localSdkPath}:${CONTAINER_LOCAL_SDK_DIR}`);
- }
-
- // Mount credentials / state individually by default so the container
- // stays isolated from the host home. Opt in to bind-mounting the
- // entire host home with OH_MOUNT_HOST_HOME=1 — useful when you want
- // the Add Workspace file browser to navigate your real host
- // filesystem (those credential subpaths come along automatically as
- // part of the same mount).
- if (process.env.OH_MOUNT_HOST_HOME === "1") {
- dockerArgs.push("-v", `${home}:${CONTAINER_HOME_DIR}`);
- } else {
- dockerArgs.push(...getDockerHomeTmpfsArgs(userSpec));
-
- const optionalMounts = [
- [join(home, ".openhands"), CONTAINER_OPENHANDS_DIR],
- [join(home, ".claude"), `${CONTAINER_HOME_DIR}/.claude`],
- // Recent Claude Code CLI versions persist auth + workspace state in
- // ``~/.claude.json`` next to (not inside) the ``~/.claude/`` directory.
- // Without this single-file mount, an ACPAgent spawned via
- // ``npx -y @zed-industries/claude-code-acp`` can't see the user's
- // existing CLI login and prompts for re-auth inside the sandbox.
- [join(home, ".claude.json"), `${CONTAINER_HOME_DIR}/.claude.json`],
- [join(home, ".codex"), `${CONTAINER_HOME_DIR}/.codex`],
- [join(home, ".ssh"), `${CONTAINER_HOME_DIR}/.ssh`],
- ];
- for (const [src, dest] of optionalMounts) {
- if (existsSync(src)) {
- dockerArgs.push("-v", `${src}:${dest}`);
- }
- }
- }
-
- // Map agent-server's in-container port (8000) to the host port the
- // ingress proxy expects.
- dockerArgs.push("-p", `${config.agentServerPort}:8000`);
-
- // Environment variables for the agent-server inside the container.
- // These mirror buildAgentServerEnv() from dev-safe.mjs but use paths
- // that exist inside the container (under the mounted ~/.openhands).
- const containerEnv = {
- HOME: CONTAINER_HOME_DIR,
- ...buildAgentServerAutomationEnv(config),
- OH_CONVERSATIONS_PATH: `${CONTAINER_OPENHANDS_DIR}/agent-canvas/conversations`,
- OH_PERSISTENCE_DIR: CONTAINER_OPENHANDS_DIR,
- OH_BASH_EVENTS_DIR: `${CONTAINER_OPENHANDS_DIR}/agent-canvas/bash_events`,
- OH_SECRET_KEY: process.env.OH_SECRET_KEY || DEFAULT_SECRET_KEY,
- // Required so the secret-seeding PUT /api/settings/secrets call from
- // the host can authenticate against the agent-server in the container.
- OH_SESSION_API_KEYS_0: config.sessionApiKey,
- // Alias for the agent-server's own URL. The agent-server itself sets
- // OH_INTERNAL_SERVER_URL=http://127.0.0.1:8000 at startup (host
- // 0.0.0.0 is rewritten to loopback) and the value is inherited by
- // every bash subprocess it spawns — including the automation run's
- // main.py / setup.sh. Those scripts read AGENT_SERVER_URL (the
- // canonical SDK name) instead of the OH_-prefixed variant, so we
- // mirror it here. 127.0.0.1:8000 is the agent-server's own URL from
- // *inside* its container (it always listens on port 8000 in
- // dev:docker).
- //
- // We deliberately do NOT set a SESSION_API_KEY alias: the SDK's
- // sanitized_env() would strip it from bash subprocesses anyway, and
- // a follow-up change to the automation preset reads
- // OH_SESSION_API_KEYS_0 directly (which is already in env).
- AGENT_SERVER_URL: "http://127.0.0.1:8000",
- // Make the mounted canvas-tools directory importable so the agent-server
- // can resolve modules listed in tool_module_qualnames (e.g. canvas_ui_tool).
- OH_EXTRA_PYTHON_PATH: CONTAINER_CANVAS_TOOLS_DIR,
- };
- for (const [k, v] of Object.entries(containerEnv)) {
- dockerArgs.push("-e", `${k}=${v}`);
- }
-
- // When using a local SDK checkout, override the image's entrypoint to
- // reinstall the four workspace packages as editable on top of the baked-in
- // venv, then exec the server. Reusing the image's venv avoids
- // redownloading transitive deps; editable installs make host-side edits
- // visible on the next module load (or container restart).
- if (localSdkPath) {
- dockerArgs.push("--entrypoint", "/bin/sh");
- }
-
- dockerArgs.push(image);
-
- if (localSdkPath) {
- const installCmd = [
- "uv pip install",
- "--python /agent-server/.venv/bin/python",
- "--reinstall",
- `-e ${CONTAINER_LOCAL_SDK_DIR}/openhands-sdk`,
- `-e ${CONTAINER_LOCAL_SDK_DIR}/openhands-tools`,
- `-e ${CONTAINER_LOCAL_SDK_DIR}/openhands-workspace`,
- `-e ${CONTAINER_LOCAL_SDK_DIR}/openhands-agent-server`,
- ].join(" ");
- const runCmd =
- "exec /agent-server/.venv/bin/python -m openhands.agent_server --host 0.0.0.0 --port 8000";
- dockerArgs.push("-c", `${installCmd} && ${runCmd}`);
- }
-
- spawnService("agent-server", "docker", dockerArgs, {
- color: c.blue,
- });
-}
-
-const isMainModule =
- process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
-
-if (isMainModule) {
- main({
- bannerTitle: "Agent Canvas + Automation Development Stack (Docker)",
- extraPrereqs: checkDockerPrereqs,
- startAgentServer: startAgentServerDocker,
- viteWorkingDir: CONTAINER_WORKSPACES_DIR,
- // The automation backend runs on the host but its dispatched
- // `mkdir -p ...` commands execute inside the agent-server container.
- // Force `AUTOMATION_WORKSPACE_BASE` to a path that exists in that
- // container so runs don't fail trying to create host paths like
- // /Users/<you>/... inside Linux. Users can still override by setting
- // AUTOMATION_WORKSPACE_BASE in their environment.
- automationWorkspaceBase: CONTAINER_WORKSPACES_DIR,
- // The automation backend tells each automation sandbox where to
- // reach it back via `AUTOMATION_API_URL` (used by setup.sh to fetch
- // /sdk-version and by the SDK to POST run completion). The sandbox
- // is a separate Docker container, so `localhost` inside it is the
- // sandbox itself — it cannot resolve `http://localhost:<ingress>`
- // to the host ingress. Use the cross-container hostname instead.
- // Users can still override by setting AUTOMATION_BASE_URL.
- automationApiHost: "host.docker.internal",
- // URL the in-sandbox bash chain uses to reach the agent-server from
- // *inside* the agent-server container itself (where automation runs
- // execute in local mode). The agent-server always listens on 8000
- // inside the container (see `dockerArgs.push("-p", "<host>:8000")`
- // above), so 127.0.0.1:8000 is the most direct route and avoids
- // bouncing through the host port-forward (which would require
- // host.docker.internal to resolve on the host — it doesn't on
- // OrbStack/colima/Linux). Users can still override by setting
- // AUTOMATION_SANDBOX_AGENT_SERVER_URL.
- sandboxAgentServerUrl: "http://127.0.0.1:8000",
- defaultStaticMode: true,
- buildStaticFrontend: buildFrontend,
- // The agent-server runs inside a Docker container in this mode, so
- // host services (ingress, automation, vite) are reachable via
- // "host.docker.internal" rather than "localhost" from the agent's POV.
- agentHostAlias: "host.docker.internal",
- mode: "dev:docker",
- }).catch((err) => {
- logError(`Fatal error: ${err.message}`);
- if (err.stack) {
- console.error(c.dim + err.stack + c.reset);
- }
- process.exit(1);
- });
-}
-
-export {
- AGENT_SERVER_REPO,
- CONTAINER_CANVAS_TOOLS_DIR,
- CONTAINER_HOME_DIR,
- CONTAINER_LOCAL_SDK_DIR,
- CONTAINER_NAME,
- CONTAINER_OPENHANDS_DIR,
- CONTAINER_WORKSPACES_DIR,
- DEFAULT_AGENT_SERVER_TAG,
- HOST_CANVAS_TOOLS_DIR,
- checkDockerPrereqs,
- getDockerHomeTmpfsArgs,
- getDockerUserArgs,
- getHostDockerUserSpec,
- getProjectsPathDockerArgs,
- isDockerPermissionDenied,
- resolveAgentServerImage,
- startAgentServerDocker,
-};
diff --git a/scripts/dev-process-utils.mjs b/scripts/dev-process-utils.mjs
index e46fc31ca3..89617daa3d 100644
--- a/scripts/dev-process-utils.mjs
+++ b/scripts/dev-process-utils.mjs
@@ -5,7 +5,7 @@ import process from "node:process";
*
* Do not use ChildProcess#killed for cleanup decisions. In Node, `killed`
* only means a signal was sent successfully; it does not mean the process has
- * exited. That distinction matters for dev launchers because uvx/npm/docker
+ * exited. That distinction matters for dev launchers because uvx/npm
* wrappers can receive SIGTERM while their long-running child process keeps
* serving on the original port.
*/
@@ -22,7 +22,6 @@ export function isProcessRunning(proc) {
*
* launcher -> uvx -> python agent-server
* launcher -> npm -> sh -> Vite
- * launcher -> docker run -> container shim
*
* Windows does not support POSIX process groups, so callers fall back to
* signaling the direct child process there.
diff --git a/scripts/dev-safe.mjs b/scripts/dev-safe.mjs
index caf558bc49..b79c763adf 100644
--- a/scripts/dev-safe.mjs
+++ b/scripts/dev-safe.mjs
@@ -50,8 +50,7 @@ export function generateRandomApiKey() {
}
// Where the auto-generated default session API key is persisted so it stays
-// stable across `npm run dev` / `npm run dev:dangerously-dockerless` /
-// `npm run dev:docker` restarts. Keeping the key stable means the value
+// stable across `npm run dev` restarts. Keeping the key stable means the value
// baked into the frontend (VITE_SESSION_API_KEY) and the persisted
// backend-registry entry (`openhands-backends` localStorage) stay in sync
// without users needing to set anything in `.env`.
@@ -631,10 +630,8 @@ export function buildAgentServerEnv(config) {
* the agent sees a `<RUNTIME_SERVICES>` block listing what's available
* without having to probe.
*
- * URLs are written from the *agent's* point of view. In dev-safe /
- * dev-with-automation the agent-server runs on the host, so the host
- * alias is "localhost". In dev-docker the agent-server runs inside a
- * container and reaches host services via "host.docker.internal".
+ * URLs are written from the *agent's* point of view. The agent-server
+ * runs on the host, so the host alias is "localhost".
*
* @param {object} options
* @param {string} [options.mode] - Human-readable dev mode label (e.g. "dev:safe").
diff --git a/scripts/dev-static.mjs b/scripts/dev-static.mjs
index 13add54e5e..9bdf675b35 100644
--- a/scripts/dev-static.mjs
+++ b/scripts/dev-static.mjs
@@ -1,7 +1,7 @@
/**
* Static-frontend Development Stack
*
- * Mirrors the dockerless automation stack but serves a production build of the
+ * Same as the default automation stack but serves a production build of the
* frontend via `scripts/static-server.mjs` instead of the Vite dev server.
* Designed for slow / flaky network situations (e.g. plane wifi)
* where Vite's ~1000 individual module requests per page load are the
@@ -24,12 +24,12 @@
* └─────────────┘ └───────────────┘ └──────────────────┘
*
* Usage:
- * npm run dev:dangerously-dockerless
- * npm run dev:dangerously-dockerless -- --port 12000
- * npm run dev:dangerously-dockerless -- --skip-build # reuse an existing build/
- * npm run dev:dangerously-dockerless -- --automation-ref feat/my-branch
+ * npm run dev:static
+ * npm run dev:static -- --port 12000
+ * npm run dev:static -- --skip-build # reuse an existing build/
+ * npm run dev:static -- --automation-ref feat/my-branch
*
- * Environment variables (all optional, same as dev:automation):
+ * Environment variables (all optional, same as dev):
* - PORT: Ingress port (default: 8000)
* - OH_AUTOMATION_GIT_REF: Git ref for automation (default: main)
* - OH_AGENT_SERVER_GIT_REF: Git ref for agent-server
@@ -144,12 +144,12 @@ function showHelp() {
console.log(`
Agent Canvas Static-frontend Development Stack
-Runs the dockerless automation stack, but serves a production build of the
+Runs the automation stack, but serves a production build of the
frontend via scripts/static-server.mjs. Use this when a remote or flaky network
makes Vite's per-module requests painful (e.g. ngrok or plane wifi).
USAGE:
- npm run dev:dangerously-dockerless [-- options]
+ npm run dev:static [-- options]
OPTIONS:
-p, --port <port> Ingress port (default: 8000)
@@ -519,7 +519,7 @@ function printBanner(config) {
`${c.dim}Frontend served from: ${join(config.canvasPath, "build")}${c.reset}`,
);
console.log(
- `${c.dim}Edit sources, then re-run \`npm run dev:dangerously-dockerless\` to rebuild.${c.reset}`,
+ `${c.dim}Edit sources, then re-run \`npm run dev:static\` to rebuild.${c.reset}`,
);
console.log(`${c.dim}Press Ctrl+C to stop${c.reset}`);
console.log("");
@@ -573,7 +573,7 @@ async function main() {
logError(
`Port ${config.agentServerPort} is already in use — another ` +
`agent-server is running. Stop it (e.g. quit \`npm run dev\`) ` +
- `before running dev:dangerously-dockerless.`,
+ `before running dev:static.`,
);
process.exit(1);
}
diff --git a/scripts/dev-with-automation.mjs b/scripts/dev-with-automation.mjs
index 7e0d3110d7..11f660a6dd 100644
--- a/scripts/dev-with-automation.mjs
+++ b/scripts/dev-with-automation.mjs
@@ -594,46 +594,22 @@ function startAutomationBackend(config) {
cwd: config.stateDir,
env: {
// The URL the automation backend itself uses to call the
- // agent-server's REST API (tarball upload + bash dispatch). It runs
- // on the host in every dev mode (including dev:docker), so the
- // published agent-server port on `localhost` is always reachable.
- //
- // NOTE: we deliberately do *not* use `host.docker.internal` here,
- // even in dev:docker. That hostname is only seeded into the host's
- // /etc/hosts on Docker Desktop macOS; on OrbStack / colima / Linux
- // hosts it doesn't resolve, and the dispatcher's very first
- // `_upload` call fails with `[Errno 8] nodename nor servname
- // provided` — dispatch never reaches `_start_bash`, so
- // `bash_command_id` stays NULL on every run.
- //
- // The companion `AUTOMATION_SANDBOX_AGENT_SERVER_URL` below
- // controls the URL exported into the in-sandbox bash chain, which
- // does need to be reachable from inside the agent-server container.
+ // agent-server's REST API (tarball upload + bash dispatch).
//
// Priority:
// 1. AUTOMATION_AGENT_SERVER_URL explicitly set in the user's env
- // 2. `localhost:<agentServerPort>` (the published port, works
- // from the host in every dev mode)
+ // 2. `localhost:<agentServerPort>`
AUTOMATION_AGENT_SERVER_URL:
process.env.AUTOMATION_AGENT_SERVER_URL ||
`http://localhost:${config.agentServerPort}`,
// The URL exported into the in-sandbox bash chain as
// `AGENT_SERVER_URL` (read by main.py / setup.sh to call back into
- // the agent-server). Only meaningful when the bash chain runs in a
- // different network namespace than the host — i.e. dev:docker.
- // In that mode the bash chain runs inside the agent-server
- // container, where the agent-server is at 127.0.0.1:8000.
- //
- // Requires automation backend support for
- // AUTOMATION_SANDBOX_AGENT_SERVER_URL (OpenHands/automation#125).
- // Older backends ignore it and fall back to
- // AUTOMATION_AGENT_SERVER_URL.
+ // the agent-server).
//
// Priority:
// 1. AUTOMATION_SANDBOX_AGENT_SERVER_URL explicitly set in env
- // 2. launcher-provided value (dev-docker.mjs)
- // 3. unset — backend falls back to AUTOMATION_AGENT_SERVER_URL,
- // which is correct for dockerless modes
+ // 2. launcher-provided value
+ // 3. unset — backend falls back to AUTOMATION_AGENT_SERVER_URL
...(process.env.AUTOMATION_SANDBOX_AGENT_SERVER_URL ||
config.sandboxAgentServerUrl
? {
@@ -647,28 +623,20 @@ function startAutomationBackend(config) {
// The automation backend uses this as its publicly-reachable base
// URL: it's appended to callback URLs and injected into each
// sandbox as `AUTOMATION_API_URL` (consumed by setup.sh for
- // /sdk-version and by the SDK for run completion). In dev:docker
- // the sandbox is a separate container, so `localhost` won't reach
- // the host ingress — the launcher therefore passes
- // `automationApiHost: "host.docker.internal"` to override the host.
+ // /sdk-version and by the SDK for run completion).
// Priority:
// 1. AUTOMATION_BASE_URL explicitly set in the user's env
- // 2. launcher-provided host (dev-docker.mjs)
- // 3. `localhost` (correct for dockerless mode)
+ // 2. launcher-provided host
+ // 3. `localhost`
AUTOMATION_BASE_URL:
process.env.AUTOMATION_BASE_URL ||
`http://${config.automationApiHost ?? "localhost"}:${config.ingressPort}`,
- // The dispatcher (running on the host) resolves this path and
- // embeds it into a `mkdir -p ...` shell command that is then
- // executed *inside* the agent-server container. So the value must
- // be valid in the container's filesystem, not just on the host.
+ // The dispatcher resolves this path and embeds it into a
+ // `mkdir -p ...` shell command executed by the agent-server.
// Priority:
// 1. AUTOMATION_WORKSPACE_BASE explicitly set in the user's env
// 2. `automationWorkspaceBase` option passed by the launcher
- // (dev-docker.mjs sets this to a container-safe path)
- // 3. host-side default that lives under config.stateDir — fine
- // for dockerless mode where the dispatcher and agent-server
- // share the host filesystem.
+ // 3. host-side default under config.stateDir
AUTOMATION_WORKSPACE_BASE:
process.env.AUTOMATION_WORKSPACE_BASE ||
config.automationWorkspaceBase ||
@@ -951,33 +919,22 @@ async function main(options = {}) {
startAgentServer: startAgentServerOverride,
extraPrereqs,
viteWorkingDir,
- // Path (in whatever filesystem the agent-server can mkdir into) used
- // as `AUTOMATION_WORKSPACE_BASE` by the automation backend. dev-docker
- // sets this to a path that exists inside the agent-server container;
- // dockerless mode leaves it undefined so the host-side default applies.
+ // Path used as `AUTOMATION_WORKSPACE_BASE` by the automation backend.
+ // Defaults to a host-side path under config.stateDir.
automationWorkspaceBase,
// Host used in `AUTOMATION_BASE_URL` (the URL the automation sandbox
- // uses to call back into the automation backend). dev-docker sets
- // this to `host.docker.internal` so the sandbox container can reach
- // the host ingress; dockerless mode leaves it undefined and the
- // default `localhost` applies.
+ // uses to call back into the automation backend). Defaults to `localhost`.
automationApiHost,
// Value exported as `AUTOMATION_SANDBOX_AGENT_SERVER_URL` to the
// automation backend. This is the URL the in-sandbox bash chain uses
- // to reach the agent-server from *inside* whatever environment it
- // runs in. dev-docker sets this to `http://127.0.0.1:8000` (the
- // agent-server's in-container loopback) so the sandbox doesn't have
- // to bounce out through the host port-forward. Dockerless modes leave
- // it undefined and the backend falls back to AUTOMATION_AGENT_SERVER_URL.
+ // to reach the agent-server. When unset the backend falls back to
+ // AUTOMATION_AGENT_SERVER_URL.
sandboxAgentServerUrl,
staticMode: staticModeOverride,
defaultStaticMode = false,
buildStaticFrontend,
staticDir: staticDirOverride,
// Hostname the agent uses to reach services running on the host.
- // dev-docker.mjs overrides this to "host.docker.internal" because the
- // agent-server runs in a container and the host is not "localhost"
- // from its perspective.
agentHostAlias = "localhost",
// Human-readable label for the dev mode, surfaced in the agent's
// <RUNTIME_SERVICES> system-prompt block.
@@ -1001,8 +958,6 @@ async function main(options = {}) {
console.log("");
// Setup phase
- // (uvx is still required even in docker mode because the automation
- // backend runs via uvx; only the agent-server is dockerized.)
checkPrerequisites({
checkFrontendDependencies:
!useStaticMode || typeof buildStaticFrontend === "function",
diff --git a/scripts/static-build.mjs b/scripts/static-build.mjs
index 5f60f1b6f1..46df1e0927 100644
--- a/scripts/static-build.mjs
+++ b/scripts/static-build.mjs
@@ -41,7 +41,7 @@ export function buildFrontend(config, args = {}) {
env: {
...process.env,
// Bake the same default workspace path that the dynamic launcher passes
- // to Vite. Docker uses an in-container path; dockerless uses host state.
+ // to Vite.
VITE_WORKING_DIR:
config.viteWorkingDir ?? join(config.stateDir, "workspaces"),
// Bake the automation backend API key so the static frontend can talk
diff --git a/scripts/static-server.mjs b/scripts/static-server.mjs
index b0de5420c2..e0eb61efc3 100644
--- a/scripts/static-server.mjs
+++ b/scripts/static-server.mjs
@@ -1,7 +1,7 @@
/**
* Combined static file server + reverse proxy.
*
- * Replaces `sirv-cli` for the dockerless static launcher. The reason a plain static
+ * Replaces `sirv-cli` for the static launcher. The reason a plain static
* server is not enough: Vite's dev server (used by `npm run dev`) configures
* a proxy for `/api`, `/sockets`, `/server_info`, `/alive`, `/health`,
* `/ready`, `/docs`, `/redoc`, `/openapi.json` (see vite.config.ts) so
diff --git a/src/api/agent-server-adapter.ts b/src/api/agent-server-adapter.ts
index 343287ba1f..1f740234fd 100644
--- a/src/api/agent-server-adapter.ts
+++ b/src/api/agent-server-adapter.ts
@@ -59,7 +59,7 @@ export interface DirectConversationInfo {
// Module qualname for the Canvas-UI tool. The agent-server imports this via
// tool_module_qualnames; the host directory is exposed via OH_EXTRA_PYTHON_PATH
-// (see scripts/dev-docker.mjs and scripts/dev-safe.mjs).
+// (see scripts/dev-safe.mjs).
const CANVAS_UI_TOOL_NAME = "canvas_ui";
const CANVAS_UI_TOOL_MODULE = "canvas_ui_tool";
@@ -199,9 +199,9 @@ export function buildRuntimeServicesSystemSuffix(): string | undefined {
// Anchor the "don't guess" warning to the actual agent-server URL for
// this stack instead of a hardcoded port. The agent-server listens on
- // different ports across dev modes (18000 in dev:safe, 8000 in
- // dev:docker, ...), and baking the wrong port into the system prompt
- // is exactly the kind of confusion this block is meant to prevent.
+ // different ports across dev modes, and baking the wrong port into the
+ // system prompt is exactly the kind of confusion this block is meant to
+ // prevent.
const agentServerUrl = agent_server?.url_from_agent;
lines.push(
"",
diff --git a/src/components/features/home/workspace-dropdown/folder-browser-modal.tsx b/src/components/features/home/workspace-dropdown/folder-browser-modal.tsx
index 10f01351dc..f0b1c3e7bf 100644
--- a/src/components/features/home/workspace-dropdown/folder-browser-modal.tsx
+++ b/src/components/features/home/workspace-dropdown/folder-browser-modal.tsx
@@ -15,7 +15,7 @@ import { cn } from "#/utils/utils";
import FolderIcon from "#/icons/folder.svg?react";
import ChevronLeft from "#/icons/chevron-left-small.svg?react";
-const DOCKER_PROJECTS_PATH = "/projects";
+const PROJECTS_PATH = "/projects";
interface FolderBrowserModalProps {
isOpen: boolean;
@@ -83,7 +83,7 @@ function getParentPath(path: string): string | null {
return trimmed.slice(0, idx);
}
-function shouldDefaultToDockerProjects(
+function shouldDefaultToProjectsPath(
homeData: HomeDirectoryResponse | undefined,
): boolean {
return homeData?.home === "/home/openhands";
@@ -105,9 +105,7 @@ export function FolderBrowserModal({
useEffect(() => {
if (isOpen && homeData?.home && currentPath === null) {
setCurrentPath(
- shouldDefaultToDockerProjects(homeData)
- ? DOCKER_PROJECTS_PATH
- : homeData.home,
+ shouldDefaultToProjectsPath(homeData) ? PROJECTS_PATH : homeData.home,
);
}
if (!isOpen) {
@@ -136,12 +134,12 @@ export function FolderBrowserModal({
...(homeData.favorites ?? []),
];
if (
- shouldDefaultToDockerProjects(homeData) &&
- !backendFavorites.some((entry) => entry.path === DOCKER_PROJECTS_PATH)
+ shouldDefaultToProjectsPath(homeData) &&
+ !backendFavorites.some((entry) => entry.path === PROJECTS_PATH)
) {
backendFavorites.push({
- label: DOCKER_PROJECTS_PATH,
- path: DOCKER_PROJECTS_PATH,
+ label: PROJECTS_PATH,
+ path: PROJECTS_PATH,
});
}
@@ -155,12 +153,11 @@ export function FolderBrowserModal({
const subdirs = listing?.items ?? [];
const parent = currentPath ? getParentPath(currentPath) : null;
- // Signal that we're inside the dev:docker container without the host
+ // Signal that we're inside a container environment without the host
// home mounted: the agent server reports `/home/openhands` as home and
// returns no favorites (the only contents are hidden credential dirs).
// In that case there's nothing useful for the user to browse, so we
- // surface the OH_MOUNT_HOST_HOME=1 opt-in instead of the generic empty
- // state when the user navigates back to the container home.
+ // surface a hint instead of the generic empty state.
const showHostHomeHint =
homeData?.home === "/home/openhands" &&
(homeData?.favorites?.length ?? 0) === 0 &&
diff --git a/src/hooks/query/use-resolved-workspaces.ts b/src/hooks/query/use-resolved-workspaces.ts
index c5e14ffe40..d886065470 100644
--- a/src/hooks/query/use-resolved-workspaces.ts
+++ b/src/hooks/query/use-resolved-workspaces.ts
@@ -14,10 +14,9 @@ interface UseResolvedWorkspacesResult {
/**
* Implicit workspace parents that are always considered when resolving
- * workspaces. The `dev:docker` script mounts the host's PROJECTS_PATH at
- * `/projects` inside the agent-server container, so this directory is
- * effectively the user's projects root in the dockerized dev stack. We
- * surface its immediate subdirectories as workspaces automatically.
+ * workspaces. `/projects` is a well-known directory that some agent-server
+ * setups use as the projects root. We surface its immediate subdirectories
+ * as workspaces automatically in dev mode.
*
* This is a development convenience only. Production previews may point at
* arbitrary remote agent servers that do not expose the file-browser endpoint;
@@ -36,7 +35,7 @@ const IMPLICIT_WORKSPACE_PARENTS: LocalWorkspaceParent[] = [
* - the immediate subdirectories of every saved "workspace parent",
* fetched dynamically, and
* - the immediate subdirectories of any implicit, built-in parents
- * (currently just `/projects`, the dockerized dev mount point).
+ * (currently just `/projects`).
*
* Static workspaces always take precedence over a dynamic child with the
* same path so that user-selected names/ids are preserved.
diff --git a/src/i18n/translation.json b/src/i18n/translation.json
index aa1070137c..6c1c636f44 100644
--- a/src/i18n/translation.json
+++ b/src/i18n/translation.json
@@ -18394,21 +18394,21 @@
"ca": "Encara no hi ha espais de treball"
},
"HOME$HOST_HOME_NOT_MOUNTED_HINT": {
- "en": "Your host filesystem isn't visible to the agent server. Set OH_MOUNT_HOST_HOME=1 before npm run dev:docker to browse it from here.",
- "ja": "ホストのファイルシステムはエージェントサーバーから見えません。ここから参照するには、npm run dev:docker の前に OH_MOUNT_HOST_HOME=1 を設定してください。",
- "zh-CN": "代理服务器看不到您的宿主机文件系统。请在运行 npm run dev:docker 之前设置 OH_MOUNT_HOST_HOME=1,即可在此浏览。",
- "zh-TW": "代理伺服器看不到您的主機檔案系統。請在執行 npm run dev:docker 之前設定 OH_MOUNT_HOST_HOME=1,即可在此瀏覽。",
- "ko-KR": "에이전트 서버에서 호스트 파일 시스템이 보이지 않습니다. 여기서 탐색하려면 npm run dev:docker 전에 OH_MOUNT_HOST_HOME=1을 설정하세요.",
- "no": "Vertens filsystem er ikke synlig for agent-serveren. Sett OH_MOUNT_HOST_HOME=1 før npm run dev:docker for å bla gjennom det herfra.",
- "it": "Il filesystem dell'host non è visibile al server dell'agente. Imposta OH_MOUNT_HOST_HOME=1 prima di npm run dev:docker per esplorarlo da qui.",
- "pt": "O sistema de arquivos do host não está visível para o servidor do agente. Defina OH_MOUNT_HOST_HOME=1 antes de npm run dev:docker para navegá-lo daqui.",
- "es": "El sistema de archivos del anfitrión no es visible para el servidor del agente. Establece OH_MOUNT_HOST_HOME=1 antes de npm run dev:docker para explorarlo desde aquí.",
- "ar": "نظام ملفات المضيف غير مرئي لخادم الوكيل. اضبط OH_MOUNT_HOST_HOME=1 قبل npm run dev:docker لتصفحه من هنا.",
- "fr": "Le système de fichiers de l'hôte n'est pas visible par le serveur de l'agent. Définissez OH_MOUNT_HOST_HOME=1 avant npm run dev:docker pour le parcourir d'ici.",
- "tr": "Ana makine dosya sistemi ajan sunucusu tarafından görülmüyor. Buradan göz atmak için npm run dev:docker öncesinde OH_MOUNT_HOST_HOME=1 ayarlayın.",
- "de": "Das Host-Dateisystem ist für den Agenten-Server nicht sichtbar. Setze OH_MOUNT_HOST_HOME=1 vor npm run dev:docker, um es hier zu durchsuchen.",
- "uk": "Файлова система хоста не видима для сервера агента. Встановіть OH_MOUNT_HOST_HOME=1 перед npm run dev:docker, щоб переглядати її звідси.",
- "ca": "El sistema de fitxers de l'amfitrió no és visible per al servidor de l'agent. Establiu OH_MOUNT_HOST_HOME=1 abans de npm run dev:docker per navegar-hi des d'aquí."
+ "en": "The agent server cannot access this directory. Check that the path exists and is readable.",
+ "ja": "The agent server cannot access this directory. Check that the path exists and is readable.",
+ "zh-CN": "The agent server cannot access this directory. Check that the path exists and is readable.",
+ "zh-TW": "The agent server cannot access this directory. Check that the path exists and is readable.",
+ "ko-KR": "The agent server cannot access this directory. Check that the path exists and is readable.",
+ "no": "The agent server cannot access this directory. Check that the path exists and is readable.",
+ "it": "The agent server cannot access this directory. Check that the path exists and is readable.",
+ "pt": "The agent server cannot access this directory. Check that the path exists and is readable.",
+ "es": "The agent server cannot access this directory. Check that the path exists and is readable.",
+ "ar": "The agent server cannot access this directory. Check that the path exists and is readable.",
+ "fr": "The agent server cannot access this directory. Check that the path exists and is readable.",
+ "tr": "The agent server cannot access this directory. Check that the path exists and is readable.",
+ "de": "The agent server cannot access this directory. Check that the path exists and is readable.",
+ "uk": "The agent server cannot access this directory. Check that the path exists and is readable.",
+ "ca": "The agent server cannot access this directory. Check that the path exists and is readable."
},
"HOME$NO_WORKSPACE_OPTION": {
"en": "No workspace",
diff --git a/src/mocks/file-service-handlers.ts b/src/mocks/file-service-handlers.ts
index 2b16d62050..ea519c41a1 100644
--- a/src/mocks/file-service-handlers.ts
+++ b/src/mocks/file-service-handlers.ts
@@ -35,7 +35,7 @@ const MOCK_SUBDIRECTORIES_BY_PATH: Record<
"/projects/demo-app/web-client": [],
};
-const shouldReturnDockerProjectMock =
+const shouldReturnProjectMock =
typeof import.meta.env.MODE === "string" && import.meta.env.MODE !== "test";
export const FILE_SERVICE_HANDLERS = [
@@ -54,7 +54,7 @@ export const FILE_SERVICE_HANDLERS = [
http.get("*/api/file/search_subdirs", async ({ request }) => {
const url = new URL(request.url);
const path = url.searchParams.get("path") ?? "";
- const items = shouldReturnDockerProjectMock
+ const items = shouldReturnProjectMock
? (MOCK_SUBDIRECTORIES_BY_PATH[path] ?? [])
: [];
diff --git a/tests/e2e/snapshots/docker-workspace-browser.snapshot.spec.ts b/tests/e2e/snapshots/projects-workspace-browser.snapshot.spec.ts
similarity index 92%
rename from tests/e2e/snapshots/docker-workspace-browser.snapshot.spec.ts
rename to tests/e2e/snapshots/projects-workspace-browser.snapshot.spec.ts
index eeda171c9e..12ca60af1d 100644
--- a/tests/e2e/snapshots/docker-workspace-browser.snapshot.spec.ts
+++ b/tests/e2e/snapshots/projects-workspace-browser.snapshot.spec.ts
@@ -1,7 +1,7 @@
import { expect, test } from "@playwright/test";
import { seedLocalStorage } from "./support/seed-local-storage";
-test("captures Docker /projects workspace browser state", async ({ page }) => {
+test("captures /projects workspace browser state", async ({ page }) => {
test.setTimeout(60_000);
await seedLocalStorage(page, {
@@ -45,7 +45,7 @@ test("captures Docker /projects workspace browser state", async ({ page }) => {
await expect(page.getByTestId("folder-browser-entry-demo-app")).toBeVisible();
await page.mouse.move(5, 5);
- await expect(modal).toHaveScreenshot("docker-projects-workspace-browser.png");
+ await expect(modal).toHaveScreenshot("projects-workspace-browser.png");
await page.getByTestId("folder-browser-entry-demo-app").click();
await expect(page.getByTestId("folder-browser-current-path")).toHaveText(