Skip to content

🙌 OpenHands: AI-Driven Development

Prepare docs for incubator review (#605)

chuckbutkus2075506f6e5f
diff --git a/README.md b/README.md
index 0e72a0b3d9..9c73f59af1 100644
--- a/README.md
+++ b/README.md
@@ -1,7 +1,9 @@
# agent-canvas
> [!WARNING]
-> This project is in alpha phase. It may be vibecoded, untested, or out of date. [Learn more](https://github.com/OpenHands/incubator-program).
+> This project is in the **Beta** 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).
+
+[![Project Status: Beta](https://img.shields.io/badge/status-beta-blue)](https://github.com/OpenHands/incubator-program)
OpenHands is a platform for orchestrating coding agents across different environments. You can:
@@ -21,10 +23,16 @@ The same Agent Canvas frontend can swap between each of these environments, so y
OpenHands works with any agent harness (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)
+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" />
+## Project ownership and support
+
+- **Current status**: Beta.
+- **Support channel**: [#proj-agent-canvas](https://openhands.dev/joinslack).
+- **Support level**: Best effort while the project remains in Beta.
+
## Quickstart
You can install OpenHands to run agents on any machine: on your laptop, on a dedicated computer like a Mac Mini,
@@ -32,7 +40,7 @@ or on a server in the cloud.
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. See [SELF_HOSTING.md](SELF_HOSTING.md) for details, especially with respect to security hardening.
+like Slack, GitHub, and Datadog. See [SELF_HOSTING.md](docs/SELF_HOSTING.md) for details, especially with respect to security hardening.
Notably, you can run the backend in _multiple different environments_, and switch between
them from the same Agent Canvas frontend. E.g. you can share an Agent Server with your team for agents doing
@@ -100,4 +108,7 @@ The Agent Server is often paired with an [Automation Server](https://github.com/
## More documentation
-For contributor and developer workflows, including frontend-only mode, mock mode, environment variables, and build/test commands, see [DEVELOPMENT.md](./DEVELOPMENT.md).
+- [Documentation index](./docs/README.md)
+- [Architecture overview](./docs/architecture.md)
+- [Development guide](./docs/DEVELOPMENT.md)
+- [Self-hosting guide](./docs/SELF_HOSTING.md)
diff --git a/DEVELOPMENT.md b/docs/DEVELOPMENT.md
similarity index 100%
rename from DEVELOPMENT.md
rename to docs/DEVELOPMENT.md
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 0000000000..a276c33cf4
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,7 @@
+# Agent Canvas docs
+
+This directory contains the project documentation.
+
+- [Architecture](./architecture.md): system boundaries, runtime modes, and quality gates.
+- [Development guide](./DEVELOPMENT.md)
+- [Self-hosting guide](./SELF_HOSTING.md)
diff --git a/SELF_HOSTING.md b/docs/SELF_HOSTING.md
similarity index 100%
rename from SELF_HOSTING.md
rename to docs/SELF_HOSTING.md
diff --git a/docs/architecture.md b/docs/architecture.md
new file mode 100644
index 0000000000..37cb9e8fab
--- /dev/null
+++ b/docs/architecture.md
@@ -0,0 +1,82 @@
+# Agent Canvas architecture
+
+Agent Canvas is a React and TypeScript frontend for running and monitoring OpenHands agents across local, remote, and hosted environments. It is adapted from the OpenHands frontend to talk directly to the OpenHands Agent Server and related automation services.
+
+## System boundaries
+
+Agent Canvas is responsible for:
+
+- Rendering the agent conversation, terminal, browser, files, settings, and automation UI.
+- Managing frontend state for conversations, backend selection, settings, profiles, and local metadata.
+- Translating UI actions into OpenHands Agent Server API calls.
+- Packaging the UI both as a standalone app and as library entrypoints for host applications.
+
+Agent Canvas is not responsible for:
+
+- Executing agent actions directly.
+- Providing the sandbox or workspace isolation layer.
+- Hosting LLM provider credentials outside the configured backend.
+- Running scheduled or event-triggered automations without an automation backend.
+
+## Runtime services
+
+The primary backend is the [OpenHands Agent Server](https://github.com/OpenHands/software-agent-sdk/tree/main/openhands-agent-server/openhands/agent_server). Agent Canvas can connect to one or more Agent Server instances and switch between them from the UI.
+
+Optional runtime services include:
+
+- An ingress service that routes frontend, Agent Server, and automation traffic behind one local origin.
+- An Automation Server for scheduled or event-triggered agent runs.
+- OpenHands Cloud APIs for hosted sandbox and organization workflows.
+
+The development launchers expose runtime service information through `VITE_RUNTIME_SERVICES_INFO`. The frontend forwards that information into new conversations as an agent context suffix so agents can use the correct URLs instead of guessing ports.
+
+## Frontend modules
+
+The most important source areas are:
+
+- `src/api/`: service adapters for Agent Server, cloud, settings, git, skills, automations, and backend registry behavior.
+- `src/components/`: route and feature UI, including conversation, chat, browser, files, settings, backend, automation, and onboarding components.
+- `src/hooks/`: reusable React Query, state, and feature hooks.
+- `src/stores/`: Zustand state stores for conversation and UI state.
+- `src/i18n/`: translation resources and generated bundles.
+- `src/mocks/`: MSW handlers for mock-mode development and tests.
+- `bin/` and `scripts/`: CLI and development stack launchers.
+
+## Runtime modes
+
+Agent Canvas supports several modes:
+
+| Mode | Purpose |
+|---|---|
+| `npm run dev:docker` | Starts the UI with an Agent Server in a Docker sandbox. This is the default safer local workflow. |
+| `npm run dev:dangerously-dockerless` | Starts the UI and Agent Server directly on the host. This is useful for servers and trusted environments, but the agent has host filesystem access. |
+| `npm run dev:automation` | Starts the local stack with an automation backend. |
+| `npm run dev:mock` | Runs the frontend against MSW mocks for UI development and tests. |
+| `npm run build` | Builds the standalone application. |
+| `npm run build:lib` | Builds library entrypoints for embedding Agent Canvas components. |
+
+## Packaging and distribution
+
+The npm package is `@openhands/agent-canvas`. The package exposes:
+
+- The `agent-canvas` binary for launching a local stack.
+- A standalone app build.
+- Library entrypoints for browser, conversation, files, settings, sidebar, terminal, and i18n modules.
+
+Tagged releases are published through the `Publish to npm` GitHub Actions workflow using npm trusted publishing and provenance.
+
+## Quality gates
+
+The main CI workflow installs dependencies with `npm ci` and runs:
+
+- Typecheck, ESLint, and Prettier through `npm run lint`.
+- Unit and component tests through `npm test`.
+- Standalone app build through `npm run build`.
+- Library build through `npm run build:lib`.
+- Package verification through `npm pack --dry-run`.
+
+Additional workflows run visual snapshot tests and optional live end-to-end QA.
+
+## Security posture
+
+Local operation can give agents access to user workspaces. The README and self-hosting guide call out this risk and recommend Docker sandbox mode for laptop usage. Self-hosted deployments should use normal server hardening practices, authentication, HTTPS, firewall rules, and careful workspace scoping.