Skip to content

🙌 OpenHands: AI-Driven Development

Update README.md: elevate dockerless installation and remove extraneous installation instructions (#576)

Robert Brennanf189713e9de5
diff --git a/README.md b/README.md
index 0f2cd08603..ebf0936e39 100644
--- a/README.md
+++ b/README.md
@@ -3,11 +3,11 @@
> [!WARNING]
> This project is in alpha phase. It may be vibecoded, untested, or out of date. [Learn more](https://github.com/OpenHands/incubator-program).
-Agent Canvas is a web frontend for managing agents. You can:
+OpenHands is a platform for managing agents across a variety of environments. You can:
-- ⌨️ prompt them manually
-- 🕐 run them on a schedule
-- ⚡ trigger them automatically — e.g. from Slack or GitHub.
+- ⌨️ prompt agents manually
+- 🕐 run agents on a schedule
+- ⚡ trigger agents automatically — e.g. from Slack, GitHub, or Datadog.
Agents can run anywhere:
@@ -24,69 +24,59 @@ If you have questions or feedback, please open a GitHub issue or join the [#proj
## Quickstart
-### With Docker (recommended)
+### Direct Install
+
+> [!WARNING]
+> This runs the agent-server directly on the machine you're installing on--the agent will have full access to your filesystem!
+>
+> We recommend running on a dedicated machine, such as a VM in DigitalOcean or a dedicated Mac Mini.
+> See [SELF_HOSTING.md](SELF_HOSTING.md) for details, especially with respect to security hardening.
+
+The most powerful way to run OpenHands is on a server in the cloud. This allows your agents to continue running
+even when your laptop is shut, and makes it easier to trigger your agents through third-party services
+like Slack, GitHub, and Datadog.
+
+Notably, you can run the OpenHands Agent Server backend on _multiple different VMs_ and switch between
+them from the same Agent Canvas frontend!
**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.
-
-By default the container runs as your host UID/GID so files written to bind mounts remain writable from your host account. The container is still kept isolated from your host home: its `/home/openhands` is a temporary writable home, and only `~/.openhands`, `~/.claude`, `~/.codex`, and `~/.ssh` are mounted individually under it (and only if they exist). If you want the **Add Workspace** dialog to browse your real host filesystem, set `OH_MOUNT_HOST_HOME=1` before `npm run dev:docker` to bind-mount your entire host home onto `/home/openhands` in the container. The Add Workspace modal also shows this hint inline when it detects the mount is off. 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).
+- `uv` (for running the agent server via `uvx`)
```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
-```
-
-This serves a static production build of the frontend behind the local ingress proxy. That is the recommended mode for normal use, remote access, and tunnels such as ngrok because it avoids Vite hot-reload restarts and large dev-module request bursts. If you are developing the Agent Canvas frontend itself and want live reload, use `npm run dev:docker:dynamic` instead.
-
-Windows PowerShell exception: if `npm run dev:docker` starts the backend but `localhost:8000` shows Bad Gateway, 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"
-git clone https://github.com/OpenHands/agent-canvas.git
-cd agent-canvas
-npm install
-node --env-file-if-exists=.env .\scripts\dev-docker.mjs
+npm run dev:dangerously-dockerless
```
-Access the UI at [http://localhost:8000](http://localhost:8000). The OpenAPI docs for the agent server and the automation backend are also served through the ingress proxy at [http://localhost:8000/docs](http://localhost:8000/docs) and [http://localhost:8000/api/automation/docs](http://localhost:8000/api/automation/docs).
+Access the UI at [http://localhost:8000](http://localhost:8000).
-### Without Docker
+### With Docker Sandbox
-> [!WARNING]
-> This runs the agent-server directly on the machine you're installing on--the agent will have full access to your filesystem!
+If you're running on your laptop, you likely want to sandbox OpenHands to limit the agent's access to your system.
-Running without docker is great if you're running Agent Canvas on a VM. See [SELF_HOSTING.md](SELF_HOSTING.md) for details,
-especially with respect to security hardening. Notably, you can run the backend on _multiple different VMs_ and switch between
-them from the same Agent Canvas frontend!
+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`
-- `uv` (for running the agent server via `uvx`)
+- 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:dangerously-dockerless
+npm run dev:docker
```
-Access the UI at [http://localhost:8000](http://localhost:8000). The OpenAPI docs for the agent server and the automation backend are also served through the ingress proxy at [http://localhost:8000/docs](http://localhost:8000/docs) and [http://localhost:8000/api/automation/docs](http://localhost:8000/api/automation/docs).
-
-This also serves a static production build for stability. If you are developing the Agent Canvas frontend itself and want live reload, use the dynamic dockerless command instead:
-
-```sh
-npm run dev:dangerously-dockerless:dynamic
-```
+Access the UI at [http://localhost:8000](http://localhost:8000).
# Architecture
@@ -105,46 +95,6 @@ The Agent Server is often paired with an [Automation Server](https://github.com/
<img width="1456" height="1258" alt="image" src="https://github.com/user-attachments/assets/cb6de6f5-ac30-4d04-a76a-b5c259f0c163" />
-## npm Package
-
-Agent Canvas is also available as an npm package for embedding in your own applications:
-
-> [!WARNING]
-> Agent Canvas has not published a stable release yet. Until the first stable version is available, the npm `latest` dist-tag may point to alpha, beta, or release-candidate builds, so `npm install @openhands/agent-canvas` can install a prerelease. Pin an exact version if you need predictable behavior.
-> This temporary behavior is tracked in [#395](https://github.com/OpenHands/agent-canvas/issues/395); retag `latest` to the first stable release when it ships.
-
-```bash
-npm install @openhands/agent-canvas
-```
-
-### Usage
-
-Import the full package or specific components:
-
-```typescript
-// Full package
-import { AgentServerUIProviders } from '@openhands/agent-canvas';
-
-// Individual component packages
-import { BrowserPanel } from '@openhands/agent-canvas/browser';
-import { ChatPanel } from '@openhands/agent-canvas/conversation';
-import { FileExplorer } from '@openhands/agent-canvas/files';
-import { TerminalPanel } from '@openhands/agent-canvas/terminal';
-```
-
-### Available Subpath Exports
-
-| Subpath | Description |
-|---------|-------------|
-| `@openhands/agent-canvas` | Main entry with providers and core components |
-| `@openhands/agent-canvas/browser` | Browser/preview panel components |
-| `@openhands/agent-canvas/conversation` | Chat interface and message components |
-| `@openhands/agent-canvas/files` | File explorer and editor components |
-| `@openhands/agent-canvas/settings` | Settings screens and forms |
-| `@openhands/agent-canvas/sidebar` | Sidebar navigation components |
-| `@openhands/agent-canvas/terminal` | Terminal emulator component |
-| `@openhands/agent-canvas/i18n` | Internationalization resources |
-
## More documentation
For contributor and developer workflows, including frontend-only mode, mock mode, environment variables, and build/test commands, see [DEVELOPMENT.md](./DEVELOPMENT.md).