Redrawing the product & repo boundaries
After the repo migration, the docs still described the old monolith. This PR re-draws the lines: Agent Canvas is a client, Agent Server runs things (and lives in the SDK repo), Automation Server schedules things, and Sandbox Server is community-only. Here's what moves where — grounded to the diff.
1The one-paragraph model
This is a documentation / information-architecture PR, not a code change. Its whole job is to make the docs match reality after Agent Canvas moved into the OpenHands/OpenHands repo and the agent runtime settled into the SDK repo. The core idea it teaches everywhere: a "backend" is not one blob. It is Agent Server (runs conversations + tools in a workspace) plus, optionally, Automation Server (schedules and event triggers). Agent Canvas is just the browser client that points at one of those backends. The most consequential single edit is that Sandbox Server is demoted to "community-driven, not a supported Canvas backend."
Read this if you have 15 seconds: new canonical page agent-canvas/architecture.mdx + new backend-setup/remote.mdx; every other .mdx edit is re-pointing links and renaming "Agent Canvas = UI+backend blob" → "Agent Canvas = client, Agent Server = runtime". The big llms-full.txt / docs.json churn is generated output, not hand-written content.
2Before → after: the mental model
The delta is a conceptual one — the same software, described with sharper nouns. Left is how the docs framed it; right is the model this PR installs.
Before — one "Agent Canvas" blob
"A backend is an agent server and the workspace it operates in." Execution and UI blur together.
After — client vs. services
software-agent-sdkOpenHands/automationGrounded in the rewritten architecture.mdx "Core Components" table and the backends.mdx redefinition.
3What moves where — page by page
The 24 changed files sort into four buckets. Content edits first; generated noise last.
A. Boundary re-framing (the real content)
| Page | What changed |
|---|---|
agent-canvas/backends.mdx | Redefines "backend": was "an agent server and the workspace" → now "provides Agent Server and, when automations are enabled, Automation Server." Splits the two responsibilities explicitly. |
overview/introduction.mdx | Agent Canvas reworded from "UI and backend server" → "open-source browser client and control center … connects to one or more Agent Server backends." Adds a dedicated SDK + Agent Server section; rewrites Cloud/Enterprise as managed control planes. |
sdk/arch/overview.mdx | "Relationship with OpenHands Applications" rewritten: SDK repo also contains Agent Server; apps (Canvas, CLI, custom) live in separate repos and consume SDK/Agent Server. Mermaid diagram relabeled Interfaces → Clients and adds an Agent Server node. |
agent-canvas/agent-profiles.mdx | Clarifies ACP ownership: "Agent Server starts and manages the ACP process, while Agent Canvas renders the conversation and profile controls." |
overview/faqs.mdx | "Is it safe?" rewritten away from "always a Docker sandbox" → "safety depends on the backend and workspace you select" (local process vs Docker/K8s/Sandbox/Cloud/Enterprise). More honest about a local backend running on the host. |
api/v1.mdx | V1 API reassigned to Sandbox Server (the community project), matching the demotion. |
enterprise/enterprise-vs-oss.mdx | "Try Agent Canvas" link re-pointed from the old run-openhands/local-setup#start-the-app to the new agent-canvas/setup. |
B. URL / path corrections (migration side-effects)
| Page | Fix |
|---|---|
backend-setup/docker.mdx, kubernetes.mdx | UI URL corrected to http://localhost:8000/canvas (backend base URL stays :8000). Docker page reworded to "Canvas client, Agent Server, Automation Server, and ingress in one container." |
backend-setup/modal.mdx | Points at OpenHands/OpenHands as "Agent Canvas Backend" rather than "the agent server" from the old repo. |
overview/contributing.mdx | Dev setup swapped from the old Python/Poetry/make flow to the new npm install / npm run dev flow; dead links (project boards, frontend/backend/agenthub READMEs) removed. |
backend-setup/cloud.mdx | Adds a "phone & tablet access" bullet. (minor marketing line — flagged below.) |
agent-canvas/ overview, setup, conversations, customize-and-settings, prebuilt-automations | One-line wording/link touch-ups to the new nouns. |
C. Navigation & generated output
docs.json nav | +47/−21 — adds the new architecture & remote pages to the Agent Canvas group; moves Modal under self-hosted backend services. |
llms-full.txt, llms.txt generated | +1323/−898 and +11/−11 — machine-generated by scripts/generate-llms-files.py. Not hand-written; the script was updated to exclude the obsolete monorepo architecture/runtime pages from LLM context. |
scripts/generate-llms-files.py + tests/test_generate_llms_files.py | The exclusion logic + a new test for it. The only "code" in the PR. |
4The two new pages
These carry the load — everything else re-points to them.
agent-canvas/architecture.mdx new
The canonical answer to "how does Canvas connect to execution, automation, and sandbox services." Opens with the load-bearing sentence — "Agent Canvas … presents backend state and sends requests; it is not an agent runtime or sandbox." — then a Core Components table mapping each component to its real repo (Canvas → OpenHands/OpenHands, Agent Server → software-agent-sdk/openhands-agent-server, Automation → OpenHands/automation). Establishes the browser path Browser → Agent Canvas → selected backend, and that a distribution may expose both services behind one URL while keeping them separate responsibilities.
backend-setup/remote.mdx new
Fills a real gap: "a remote backend is an Agent Server endpoint that runs somewhere other than the client — same API as local." Lists what a remote backend must provide (URL, API key, workspace/sandbox; + Automation Server for schedules), the connect steps, a security warning about exposing a backend, and a deployment-examples table pointing to local / VM / Docker / K8s / Modal / Cloud.
5The language shift, in one line
Almost every content edit is the same substitution applied consistently:
"Agent Canvas = the app that runs agents" → "Agent Canvas = the client; Agent Server = the runtime; Automation Server = the scheduler; the workspace/sandbox = the boundary."
That's the spine of the PR. If you agree with that sentence, you agree with ~80% of the diff. The remaining 20% is where to draw the Sandbox Server line and a couple of marketing/wording calls.
6What I'd double-check (page-by-page review notes)
- Sandbox Server demotion decide — this is the one genuinely load-bearing product call, not just a rename. "Community-driven, not a supported Canvas backend" appears in
architecture.mdxand reassigns the whole V1 API page. Worth a maintainer confirming that's the intended positioning before it's published. cloud.mdx"Easy Phone & Tablet Access so you can code on the go" tone — reads like a marketing line dropped into a setup doc; capitalization is off-style vs the rest of the page. Small, but it stands out.- The
/canvasURL change verify — docker/k8s pages now say the UI is at:8000/canvaswhile the backend base URL stays:8000. Good to confirm that split path is actually what the shipped ingress serves (it matches what I see locally, FWIW). - Draft + first pass — the author explicitly says keep it in draft; it's a broad first sweep over issue #686 and wants page-by-page review for IA and technical accuracy. The generated
llms-full.txtchurn makes the diff look scarier than the hand-written change is. - Pre-existing test failures — the pricing suite has two failures unrelated to this PR (they fetch a removed
OpenHands/utils/llm.pypath). Not introduced here; flagged so it isn't mistaken for a regression.
7The feline view 🐾
Good instinct, right target. The old docs described a monolith that no longer exists, and this untangles it into the four nouns that are actually true after the migration. The strongest move is making "backend = Agent Server (+ optional Automation Server)" explicit everywhere — that's the mental model people kept getting wrong, and it's now consistent across intro, backends, architecture, and the SDK overview.
Two cautions before merge: (1) the Sandbox Server "community-only" line is a product decision wearing a docs-edit costume — get a human yes on it. (2) Trim the phone/tablet marketing line, or move it somewhere it belongs. Everything else is clean, honest re-pointing. I'd approve the direction and ask for the page-by-page pass the author already requested — especially the architecture page's component/repo table, since that becomes the thing everyone links to.
Scope honesty: I read the PR diff, not the rendered Mintlify preview. Claims here are grounded in the .mdx patches; the two .txt files are generated and I treated them as such.
Source: github.com/OpenHands/docs/pull/688/files