@openhands/agent-canvas 1.0.0-alpha.1

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright © 2025 OpenHands contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the “Software”), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,128 @@
+# agent-canvas
+
+> [!WARNING]
+> This project is in sandbox phase. It may be vibecoded, untested, or out of date. OpenHands takes no responsibility for the code or its support. [Learn more](https://github.com/OpenHands/incubator-program).
+
+Agent Canvas is a web frontend for managing agents. You can:
+
+- ⌨️ prompt them manually
+- 🕐 run them on a schedule
+- ⚡ trigger them automatically—e.g. from Slack or GitHub.
+
+Agents can run anywhere:
+
+- 🧑‍💻 on your laptop
+- 🖥️ on a remote virtual machine
+- ☁️ in our hosted cloud
+- 🏢 or inside your company’s infrastructure
+
+You can work with any agent (e.g. Claude Code, Codex) or connect directly to an LLM (e.g. Anthropic, OpenAI, Gemini, Mistral, Minimax, Kimi).
+
+If you have questions or feedback, please open a GitHub issue or join the [#proj-agent-canvas channel in Slack](https://openhands.dev/joinslack)
+
+<img width="1509" height="826" alt="Screenshot 2026-05-11 at 10 13 19 AM" src="https://github.com/user-attachments/assets/71ef41ae-8f6d-4fbf-990f-d672175d93d1" />
+
+## Quickstart
+
+### With Docker (recommended)
+
+**Prerequisites**:
+
+- Node.js 22.12.x or later
+- `npm`
+- Docker
+
+Set `$PROJECT_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 is kept isolated from your host home — only `~/.openhands`, `~/.claude`, `~/.codex`, and `~/.ssh` are mounted individually (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.
+
+```sh
+export PROJECT_PATH=/path/to/your/projects
+git clone https://github.com/OpenHands/agent-canvas.git
+cd agent-canvas
+npm install
+npm run dev:docker
+```
+
+Access the UI at [http://localhost:8000](http://localhost:8000)
+
+### Without Docker
+
+> [!WARNING]
+> This runs the agent-server directly on the machine you're installing on--the agent will have full access to your filesystem!
+
+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!
+
+**Prerequisites**:
+
+- Node.js 22.12.x or later
+- `npm`
+- `uv` (for running the agent server via `uvx`)
+
+```sh
+git clone https://github.com/OpenHands/agent-canvas.git
+cd agent-canvas
+npm install
+npm run dev:dangerously-dockerless
+```
+
+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.
+
+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.
+
+<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:
+
+```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 { ChatInterface } from '@openhands/agent-canvas/conversation';
+import { FileExplorer } from '@openhands/agent-canvas/files';
+import { Terminal } 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).

package/package.json

@@ -0,0 +1,207 @@
+{
+  "name": "@openhands/agent-canvas",
+  "version": "1.0.0-alpha.1",
+  "license": "MIT",
+  "private": false,
+  "type": "module",
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "dependencies": {
+    "@heroui/react": "2.8.10",
+    "@microlink/react-json-view": "1.31.19",
+    "@monaco-editor/react": "4.7.0",
+    "@openhands/typescript-client": "github:OpenHands/typescript-client#ef62e82fc3dfb03991a1c8025429caf354427263",
+    "@react-router/node": "7.14.2",
+    "@react-router/serve": "7.14.2",
+    "@tailwindcss/vite": "4.2.4",
+    "@tanstack/react-query": "5.100.6",
+    "@uidotdev/usehooks": "2.4.1",
+    "@xterm/addon-fit": "0.11.0",
+    "@xterm/xterm": "6.0.0",
+    "axios": "1.15.2",
+    "class-variance-authority": "0.7.1",
+    "clsx": "2.1.1",
+    "downshift": "9.3.2",
+    "eslint-config-airbnb-typescript": "18.0.0",
+    "framer-motion": "12.38.0",
+    "i18next": "26.0.8",
+    "i18next-browser-languagedetector": "8.2.1",
+    "i18next-http-backend": "3.0.6",
+    "isbot": "5.1.39",
+    "lucide-react": "1.14.0",
+    "monaco-editor": "0.55.1",
+    "posthog-js": "1.372.5",
+    "react": "19.2.5",
+    "react-dom": "19.2.5",
+    "react-hot-toast": "2.6.0",
+    "react-i18next": "17.0.6",
+    "react-icons": "5.6.0",
+    "react-markdown": "10.1.0",
+    "react-router": "7.14.2",
+    "react-syntax-highlighter": "16.1.1",
+    "rehype-raw": "7.0.0",
+    "rehype-sanitize": "6.0.0",
+    "remark-breaks": "4.0.0",
+    "remark-gfm": "4.0.1",
+    "sirv-cli": "3.0.1",
+    "socket.io-client": "4.8.3",
+    "tailwind-merge": "3.5.0",
+    "tailwind-scrollbar": "4.0.2",
+    "uuid": "^14.0.0",
+    "vite": "8.0.10",
+    "zustand": "5.0.12"
+  },
+  "scripts": {
+    "dev": "npm run dev:docker",
+    "dev:dangerously-dockerless": "npm run dev:automation",
+    "dev:safe": "node --env-file-if-exists=.env scripts/dev-safe.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:static": "node --env-file-if-exists=.env scripts/dev-static.mjs",
+    "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",
+    "build": "npm run build:app",
+    "build:mock": "npm run make-i18n && cross-env VITE_MOCK_API=true react-router build",
+    "start": "npx sirv-cli build/ --single",
+    "test": "npm run make-i18n && vitest run",
+    "test:e2e": "playwright test",
+    "test:coverage": "npm run make-i18n && vitest run --coverage",
+    "dev_wsl": "VITE_WATCH_USE_POLLING=true vite",
+    "preview": "vite preview",
+    "make-i18n": "node scripts/make-i18n-translations.cjs",
+    "prelint": "npm run make-i18n",
+    "lint": "npm run typecheck && eslint src --ext .ts,.tsx,.js && prettier --check src/**/*.{ts,tsx}",
+    "lint:fix": "eslint src --ext .ts,.tsx,.js --fix && prettier --write src/**/*.{ts,tsx}",
+    "prepare": "cd .. && husky frontend/.husky",
+    "typecheck": "react-router typegen && tsc",
+    "typecheck:staged": "react-router typegen && npx tsc --noEmit --skipLibCheck",
+    "check-translation-completeness": "node scripts/check-translation-completeness.cjs",
+    "build:app": "npm run make-i18n && react-router build",
+    "build:lib": "npm run make-i18n && react-router typegen && cross-env BUILD_LIB=true vite build && tsc -p tsconfig.lib.json"
+  },
+  "lint-staged": {
+    "src/**/*.{ts,tsx,js}": [
+      "eslint --fix",
+      "prettier --write"
+    ],
+    "src/**/*.{ts,tsx}": [
+      "bash -c 'npm run typecheck:staged'"
+    ],
+    "src/**/*": [
+      "npm run check-translation-completeness"
+    ]
+  },
+  "devDependencies": {
+    "@mswjs/socket.io-binding": "0.2.0",
+    "@playwright/test": "1.59.1",
+    "@react-router/dev": "7.14.2",
+    "@tailwindcss/typography": "0.5.19",
+    "@tanstack/eslint-plugin-query": "5.100.6",
+    "@testing-library/dom": "10.4.1",
+    "@testing-library/jest-dom": "6.9.1",
+    "@testing-library/react": "16.3.2",
+    "@testing-library/user-event": "14.6.1",
+    "@types/node": "25.6.0",
+    "@types/react": "19.2.14",
+    "@types/react-dom": "19.2.3",
+    "@types/react-syntax-highlighter": "15.5.13",
+    "@typescript-eslint/eslint-plugin": "7.18.0",
+    "@typescript-eslint/parser": "7.18.0",
+    "@vercel/react-router": "1.2.6",
+    "@vitest/coverage-v8": "4.1.5",
+    "cross-env": "10.1.0",
+    "eslint": "8.57.1",
+    "eslint-config-airbnb": "19.0.4",
+    "eslint-config-airbnb-typescript": "18.0.0",
+    "eslint-config-prettier": "10.1.8",
+    "eslint-plugin-i18next": "6.1.4",
+    "eslint-plugin-import": "2.32.0",
+    "eslint-plugin-jsx-a11y": "6.10.2",
+    "eslint-plugin-prettier": "5.5.5",
+    "eslint-plugin-react": "7.37.5",
+    "eslint-plugin-react-hooks": "7.1.1",
+    "eslint-plugin-unused-imports": "4.4.1",
+    "husky": "9.1.7",
+    "jsdom": "29.1.1",
+    "lint-staged": "16.4.0",
+    "msw": "2.14.2",
+    "postcss-prefix-selector": "2.1.1",
+    "prettier": "3.8.3",
+    "tailwindcss": "4.2.4",
+    "typescript": "6.0.3",
+    "vite-plugin-svgr": "5.2.0",
+    "vitest": "4.1.5"
+  },
+  "packageManager": "npm@10.5.0",
+  "volta": {
+    "node": "22.12.0"
+  },
+  "msw": {
+    "workerDirectory": [
+      "public"
+    ]
+  },
+  "overrides": {
+    "dompurify": "3.3.2",
+    "eslint-config-airbnb": {
+      "eslint-plugin-react-hooks": "$eslint-plugin-react-hooks"
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./browser": {
+      "types": "./dist/components/browser/index.d.ts",
+      "import": "./dist/components/browser/index.js",
+      "require": "./dist/components/browser/index.cjs"
+    },
+    "./conversation": {
+      "types": "./dist/components/conversation/index.d.ts",
+      "import": "./dist/components/conversation/index.js",
+      "require": "./dist/components/conversation/index.cjs"
+    },
+    "./files": {
+      "types": "./dist/components/files/index.d.ts",
+      "import": "./dist/components/files/index.js",
+      "require": "./dist/components/files/index.cjs"
+    },
+    "./settings": {
+      "types": "./dist/components/settings/index.d.ts",
+      "import": "./dist/components/settings/index.js",
+      "require": "./dist/components/settings/index.cjs"
+    },
+    "./sidebar": {
+      "types": "./dist/components/sidebar/index.d.ts",
+      "import": "./dist/components/sidebar/index.js",
+      "require": "./dist/components/sidebar/index.cjs"
+    },
+    "./terminal": {
+      "types": "./dist/components/terminal/index.d.ts",
+      "import": "./dist/components/terminal/index.js",
+      "require": "./dist/components/terminal/index.cjs"
+    },
+    "./i18n": {
+      "types": "./dist/i18n/index.d.ts",
+      "import": "./dist/i18n/index.js",
+      "require": "./dist/i18n/index.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "peerDependencies": {
+    "react": "19.2.5",
+    "react-dom": "19.2.5",
+    "react-router": "7.14.2"
+  }
+}