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. 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 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.