Update docs for new repository boundaries and Agent Canvas architecture

[DevinVinson]

Summary

The recent repository migration changed the ownership and architecture boundaries that the documentation currently teaches:

• OpenHands/OpenHands is now the home of Agent Canvas.
• OpenHands/agent-canvas is an archival pointer; Agent Canvas itself is not deprecated.
• OpenHands/sandbox-server is the public standalone API and sandbox control plane, with no bundled frontend.
• OpenHands/enterprise is now private and contains commercial Enterprise development.
• OpenHands/legacy preserves the prior monorepo snapshot.
• The previous frontend is deprecated in favor of Agent Canvas.

The intended migration is documented in OpenHands/OpenHands#15396.

We should keep the Agent Canvas name, but portray it consistently as the open-source browser client and control center. Packaged distributions may start Canvas together with Agent Server and Automation Server, but Canvas itself does not execute tools or provide sandbox isolation.

Main problems found

1. The introduction describes obsolete product and source boundaries.

   • Agent Canvas is called “a browser-based UI and backend server”, conflating the client with backend services.
   • Enterprise is described as source-available in a public enterprise/ directory, which no longer exists in the public repository.
   • The licensing summary still describes the old public monorepo boundary.

2. The contributor guide still documents the former monorepo.

   • The setup instructions use the old Python/Poetry/Make workflow and link a missing Development.md.
   • The architecture links point to removed frontend/, openhands/, agenthub/, and runtime paths.
   • The Enterprise contribution warning still refers to a directory in the public repository.

3. Sandbox Server is missing from the documentation model.

   • docs.json has no Sandbox Server section or source mapping.
   • The public component that should be represented is OpenHands/sandbox-server, which owns the standalone API and sandbox control plane.

4. The V1 API is assigned to the wrong product area.

   • REST API (V1) is described generically as the API used by the Web app, despite describing Sandbox Server resources.
   • docs.json places that page under Cloud API, obscuring whether it is Cloud, Enterprise, Sandbox Server, or Agent Server API documentation.

5. Legacy monorepo architecture remains in current documentation and generated LLM context.

   • architecture/backend.mdx still presents the old frontend/backend/runtime model.
   • architecture/runtime.mdx still describes the former runtime architecture and source layout.
   • The LLM generator scans non-V0 MDX files regardless of navigation or lifecycle, so orphaned split-era pages can still enter llms-full.txt.

6. Agent Canvas pages often attribute backend responsibilities to Canvas itself.

   • The overview defines the backend as one agent server that owns conversations, tools, settings, secrets, and automations, obscuring the separate Agent Server and Automation Server roles.
   • The setup warning says “Agent Canvas starts an agent server”, when that is behavior of the launcher/distribution rather than the React client.
   • Conversation execution is attributed directly to Agent Canvas.
   • ACP process startup is attributed to Agent Canvas in the profile documentation, while Agent Server is the execution component.

7. Enterprise pages contain deprecated links and conflicting sandbox topology.

   • The Enterprise comparison sends users to deprecated Local GUI setup instead of Agent Canvas setup.
   • The conversations page allows one or several conversations in a sandbox, while resource guidance says each conversation gets its own sandbox pod.
   • The comparison page also contains stale sandboxing and product-positioning claims.

8. The unified documentation site points its global GitHub link to one component repository.

   • The navbar and footer both link to OpenHands/OpenHands, which is now specifically the Agent Canvas source repository rather than the source for the entire SDK, CLI, Sandbox Server, Cloud, and Enterprise documentation set.

Phase 1 — Correct ownership and product positioning

overview/introduction.mdx

• Add a concise component/repository map covering Agent Canvas, Agent Server, Automation Server, Sandbox Server, Cloud, Enterprise, and the legacy snapshot.
• Recast Agent Canvas as the browser client and control center.
• Describe Cloud as the managed commercial service.
• Describe Enterprise as commercial capabilities for managed Cloud and licensed self-hosting.
• Remove the public enterprise/ source claim and ecosystem-wide MIT claim.
• Link historical Local GUI source to an appropriate pinned location in OpenHands/legacy.

overview/contributing.mdx

• Replace the former monorepo setup with a contributor-routing table for:
  • Agent Canvas: OpenHands/OpenHands
  • SDK and Agent Server: OpenHands/software-agent-sdk
  • Sandbox Server: OpenHands/sandbox-server
  • CLI: OpenHands/OpenHands-CLI
  • Documentation: OpenHands/docs
  • Evaluations: OpenHands/benchmarks
• Remove obsolete source paths and the public Enterprise directory restriction.
• Point each component to its own development, issue, license, and contribution guidance where available.

Other Phase 1 corrections

• Update sdk/arch/overview.mdx so it no longer implies OpenHands/OpenHands contains the web app, CLI, and Cloud.
• Update docs.json:
  • Point the global GitHub link to the OpenHands organization or a new source-repositories page.
  • Remove the duplicated integrations-settings navigation entry.
• Correct high-confidence broken links and outdated public source references discovered during this work.

Phase 2 — Make Agent Canvas architecture explicit

Create a canonical page, proposed as openhands/usage/agent-canvas/architecture.mdx, that distinguishes the current responsibilities:

Browser → Agent Canvas
             ├─ Agent Server → workspace or sandbox → tools/agent execution
             └─ Automation Server → schedules/events/run lifecycle

Optional control plane:
Agent Canvas → Sandbox Server → sandbox → Agent Server

Remote platforms:
Agent Canvas → OpenHands Cloud or OpenHands Enterprise

The page should state two invariants prominently:

1. Agent Canvas does not execute tools.
2. Agent Canvas does not itself provide sandbox isolation. Isolation comes from the selected backend, workspace, or sandbox.

Align the terminology and responsibility boundaries in:

• agent-canvas/overview.mdx
• agent-canvas/setup.mdx
• agent-canvas/backends.mdx
• agent-canvas/conversations.mdx
• agent-canvas/agent-profiles.mdx
• agent-canvas/prebuilt/
• agent-canvas/backend-setup/

Specific changes should:

• Name Agent Server and Automation Server responsibilities directly.
• Distinguish the agent-canvas launcher/all-in-one distribution from the Canvas client.
• Add OpenHands Enterprise as a supported backend/deployment relationship.
• Verify and correct Docker and Helm UI URLs, including whether /canvas is the canonical path.
• Make clear which deployment methods bundle services and which merely connect the client to an existing backend.

Reorganize the existing Agent Canvas tab without renaming it:

1. Overview and architecture
2. Install Canvas / run the local all-in-one stack
3. Connect backends
4. Self-host backend services
5. Use Canvas
6. Automations
7. Contribute and troubleshoot

Decisions to confirm

• Should Sandbox Server receive its own top-level documentation tab, or live under a broader self-hosting/API section?
• Is “OpenHands Cloud is the managed delivery of the Enterprise platform” approved product language, or should the Cloud/Enterprise relationship be phrased more loosely?
• Is Sandbox Server intended as a supported end-user self-hosting surface now, or primarily as an operator/integration-developer component?
• Should the global GitHub link point to the OpenHands organization page or to a new repository/source map in the docs?

---

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