π OpenHands: AI-Driven Development
Development
This document is for contributors working on agent-canvas itself.
Base color and typography utilities
text-base is the standard Tailwind font-size utility (1rem with its default
line height). Canvas's base surface color uses the distinct canvas-base token:
bg-canvas-base and text-canvas-base resolve to --oh-color-base. Text on a
primary surface can use the existing text-on-primary alias.
When updating custom components or an embedding host that uses Canvas's generated
CSS, migrate bg-base to bg-canvas-base (including variants and opacity modifiers),
and migrate any intentional color use of text-base to text-canvas-base or an
appropriate semantic color. The old --color-base Tailwind alias is removed to
prevent it from taking over text-base; other *-base color utilities must use
*-canvas-base when generated by the host's Tailwind build. The runtime theme
variable --oh-color-base and the separate base-secondary token are unchanged.
Keep fixed-pixel input sizes explicit when required: replacing text-[16px] with
text-base changes its behavior when the host root font size differs from 16px,
and can introduce a default line height. Check computed styles and class merging
when migrating typography.
Recommended local workflow
npm run dev runs the full local stack (agent-server + automation backend via
uvx, Vite dev server with live reload, and an ingress proxy) β all without
Docker.
Repository boundaries
This repository contains the Agent Canvas frontend and local-stack orchestration. Use the sibling repositories for their owned layers:
OpenHands/software-agent-sdkowns the Python SDK, Agent Server, agent/tool behavior, conversations, workspaces, events, and server API.software-agent-sdk/clients/typescriptowns browser-compatible typed access to that Agent Server API. Add client methods there rather than reimplementing API calls in Canvas.OpenHands/extensionsowns reusable skills, plugins, automations, and integrations;OpenHands/automationowns automation definitions, scheduling, webhooks, run history, and dispatching; Agent Server/SDK code executes the dispatched conversations.
When a feature crosses repositories, implement the backend contract in the SDK first, expose it through typescript-client, and consume it in Canvas. Coordinate automation lifecycle changes in automation. Version pins, local-stack overrides, and PR ordering are in Cross-repository version compatibility. See the repository contributor notes and follow the custom code-review guide for every pull request.
For a static frontend build (better for slow networks, remote access, tunnels):
npm run dev:static
The published agent-canvas binary also supports partial-stack modes when you want to run the frontend and backend processes separately:
agent-canvas --frontend-only
agent-canvas --backend-only
Both modes still start the ingress proxy; the proxy only routes to the services started by that mode.
The dev stack uses uvx to run a temporary agent-server
installation on 127.0.0.1:18000 and points the frontend at it. It isolates
conversation persistence by setting separate OH_CONVERSATIONS_PATH,
OH_BASH_EVENTS_DIR, and OH_VSCODE_PORT values under .openhands-dev/, and
keeps its tmux sockets under ~/.openhands/agent-canvas/tmux (via
TMUX_TMPDIR), so it does not collide with other local or cloud-backed
OpenHands sessions. If $HOME is on a filesystem that does not support Unix
domain sockets (some devcontainers, NFS/CIFS homes), or if the complete tmux
socket path exceeds the host's Unix socket path limit, set the standard
TMUX_TMPDIR env var to a short local directory such as
/tmp/openhands-tmux-instance-a. The npm and dev launchers create the resolved
directory before starting the Agent Server and preserve an explicit override.
Environment Variables
| Variable | Description | Default |
|---|---|---|
PORT |
Ingress port | 8000 |
OH_AGENT_SERVER_LOCAL_PATH |
Absolute software-agent-sdk checkout |
unset |
OH_AGENT_SERVER_GIT_REF |
Git ref for agent-server | unset (config/defaults.json) |
OH_AGENT_SERVER_VERSION |
PyPI version for agent-server | unset (config/defaults.json) |
OH_AUTOMATION_LOCAL_PATH |
Absolute automation checkout |
unset |
OH_AUTOMATION_GIT_REF |
Git ref for automation backend | unset (config/defaults.json) |
OH_AUTOMATION_VERSION |
PyPI version for automation | unset (config/defaults.json) |
UV_PYTHON |
Python version/range for uvx services | unset (config/defaults.json) |
Alternative: Minimal Mode (without Automation)
To run without the automation service:
npm run dev:minimal
This runs only agent-server + Vite (no automation backend or ingress).
Access at http://localhost:3001/
Cross-repository version compatibility
The default local stack for this checkout is the pins recorded below, not
an open-ended matrix of sibling main branches. Connecting to another Agent
Server is allowed down to compatibility.minimumAgentServer. Mixing an
unpinned Git backend with the committed TypeScript client (or the reverse) is
unsupported and often looks like a product bug.
Owning repositories:
OpenHands/OpenHands(this repo) β Agent CanvasOpenHands/software-agent-sdkβ Python SDK and Agent Serversoftware-agent-sdk/clients/typescriptβ@openhands/typescript-clientOpenHands/automationβ scheduling, webhooks, run historyOpenHands/extensionsβ@openhands/extensionsskills and integrations
Source of truth
| Surface | Supported version lives in |
|---|---|
| Bundled Agent Server / SDK PyPI pin | config/defaults.json versions.agentServer |
| Bundled automation PyPI pin | config/defaults.json versions.automation |
| Oldest Agent Server this frontend accepts | config/defaults.json compatibility.minimumAgentServer |
@openhands/typescript-client |
package.json (exact npm pin) |
@openhands/extensions |
package.json (exact npm pin) |
| Released automation β SDK dependency match | scripts/check-sdk-version-sync.mjs |
config/defaults.json is the source of truth for the Python backend pins used
by the npm and Docker install paths. agent-canvas --info prints the same
Agent Server and automation pins plus the minimum compatible Agent Server.
Those files describe this revision. They are not a historical compatibility
matrix. They do not promise that Git main of every sibling repository works
together, or that independently chosen PyPI/npm numbers with the same major
version are interchangeable.
Runtime enforcement for a connected Agent Server is
assertAgentServerVersionIsSupported() in
src/api/agent-server-compatibility.ts.
Some UI features have additional floors inside @openhands/typescript-client.
Meeting compatibility.minimumAgentServer does not mean every Canvas feature
is available on that backend.
The TypeScript client records the Agent Server contract it was generated from
in software-agent-sdk/clients/typescript. That client
contract pin is independent of Canvas versions.agentServer.
Released package, Git ref, and local path
npm run dev, npm run dev:static, and the agent-canvas binary select
Python backends with the following precedence (highest first).
npm run dev:minimal uses the same Agent Server selection and does not start
automation. Leaving an override unset means "use the pin above", not Git
main.
Agent Server (software-agent-sdk):
OH_AGENT_SERVER_LOCAL_PATHβ absolute path to a checkout that containsopenhands-agent-server,openhands-sdk,openhands-tools, andopenhands-workspace. The agent-server package is rebuilt from local source on each start (uvx --reinstall); the other workspace packages are installed editable.OH_AGENT_SERVER_GIT_REFβ branch, tag, or commit. All four workspace packages are installed from that same ref so inter-package APIs stay in sync. The launcher passesuvx --reinstallso a cached PyPI wheel with the same version string is not reused.OH_AGENT_SERVER_VERSIONβ a specific PyPI version of those four packages.- Default:
versions.agentServerfromconfig/defaults.json.
OH_AGENT_SERVER_LOCAL_PATH=/abs/path/to/software-agent-sdk npm run dev
OH_AGENT_SERVER_GIT_REF=<branch-or-sha> npm run dev
OH_AGENT_SERVER_VERSION=<versions.agentServer> npm run dev
Automation (automation):
OH_AUTOMATION_LOCAL_PATHβ absolute path to a checkout withpyproject.toml.--automation-refon the launcher outranks this local path.OH_AUTOMATION_GIT_REF(or--automation-ref) β branch, tag, or commit.OH_AUTOMATION_REPOonly applies when a git ref is selected.OH_AUTOMATION_VERSIONβ a specific PyPI version ofopenhands-automation.- Default:
versions.automationfromconfig/defaults.json.
Released openhands-automation is checked against versions.agentServer.
CI runs scripts/check-sdk-version-sync.mjs on the published automation
package, not on a local checkout or Git main.
TypeScript client and extensions: Canvas does not provide Git-ref or
local-path launcher variables for @openhands/typescript-client or
@openhands/extensions. Both are exact npm pins in package.json. Public
skills are loaded from @openhands/extensions at build time; the Agent
Server no longer clones the extensions repo or honors EXTENSIONS_REF.
Contributor notes require a published TypeScript client before Canvas bumps that pin. Do not point this repository at an unpublished commit SHA.
Iterate on unreleased client work in software-agent-sdk/clients/typescript
and extensions work in OpenHands/extensions, then
bump the Canvas pin after the package exists on the registry.
Cross-repository change checklist
- Confirm ownership using Repository boundaries.
- Read
config/defaults.jsonandpackage.jsonfor the pins this Canvas revision expects. - If the Agent Server API changes, land it in
software-agent-sdkfirst. For local Canvas testing, useOH_AGENT_SERVER_LOCAL_PATHorOH_AGENT_SERVER_GIT_REF; keep the TypeScript client pin until the client is published. - Mirror the contract in
software-agent-sdk/clients/typescript(OpenAPI and handwritten clients). Publish that package, then bump@openhands/typescript-clienthere. - If automation must run against the new SDK, release
openhands-automationwith matching SDK dependencies, then updateversions.automationsoscripts/check-sdk-version-sync.mjsstill passes. - If public skills or integrations change, publish
@openhands/extensionsand then bump that dependency. - If a Canvas PR needs an unreleased Agent Server, link the
OpenHands/software-agent-sdkpull request and record the local-path or Git-ref verification in the Canvas PR body. E2E workflows run after changes reachmain; for risky pre-merge changes, ask a maintainer to manually dispatch the relevant workflow against the PR branch. Do not assume a PR link automatically installs an SDK ref in mock-LLM Docker E2E. - Do not merge Canvas UI that requires a contract the pinned client does not yet expose.
Breaking contract sequencing
Usual direction: Agent Server / SDK β OpenAPI contract β typescript-client β
Agent Canvas. Automation scheduling flows Canvas β automation β Agent
Server / SDK.
REST deprecation and the removal runway are owned by
software-agent-sdk (openhands-agent-server/AGENTS.md). Canvas must not
skip the client release step or consume an unpublished client SHA.
Event wire types follow the same order: SDK Pydantic model, then TypeScript client, then Canvas consumption of the client type. See the custom code-review guide.
Other useful overrides
OH_CANVAS_SAFE_BACKEND_PORTβ backend port for the isolated server (default18000)OH_CANVAS_SAFE_VSCODE_PORTβ VS Code sidecar port (defaultbackend port + 1)OH_CANVAS_SAFE_STATE_DIRβ base directory for isolated server stateVITE_WORKING_DIRβ repo root used for new conversations (defaults to the current checkout)
Alternative development workflows
Multiple local backends (shared persistence)
To run a second standalone agent-server alongside npm run dev while sharing
its conversation history and encrypted secrets, you can use the
npm run dev:extra-backend helper. It launches an extra server on :18002 that
reuses the bundled instance's state dir.
Frontend against an existing backend
Use this only if you intentionally started agent-server yourself or want the frontend to talk to another backend:
npm run dev:frontend
The frontend-only workflow expects the backend at 127.0.0.1:8000 by default.
If you set LOCAL_BACKEND_API_KEY, it is used as the API key for the agent-server (mapped internally to OH_SESSION_API_KEYS_0). The launcher auto-generates and persists a key when LOCAL_BACKEND_API_KEY is not set.
Mock mode
If you want to run the frontend without a live backend, use:
npm run dev:mock
Build and test
npm run test
npm run build
npm run start
Useful targeted verification for the isolated dev launcher:
npm run test -- __tests__/api/agent-server-config.test.ts __tests__/scripts/dev-safe.test.ts
Unit test environments
npm test runs Vitest as two projects, so each suite pays only for the
environment it actually needs:
| Project | Environment | Setup | Suites |
|---|---|---|---|
jsdom |
jsdom |
vitest.setup.ts |
everything else (the default) |
node |
node |
none | the DOM-free suites listed in NODE_ENV_PILOT_TESTS in vite.config.ts |
Both projects run in a single npm test, and the Node list is excluded from
the jsdom project, so every suite runs exactly once. Vitest prefixes each
result with its project name (|node| / |jsdom|) when a test fails or when
you pass --reporter=verbose.
The Node project exists because jsdom is not free: it costs roughly a second of
environment setup per run, plus the whole of vitest.setup.ts (Testing Library
cleanup, MSW, jest-dom, DOM global stubs). Suites that only call pure functions
need none of it.
Adding a suite to the Node project
A suite qualifies only if all of the following hold. Check the suite and everything it imports, transitively β an import that touches the DOM at module scope is enough to disqualify it.
- No DOM: no
document,window,HTMLElement,navigator, or@testing-library/*rendering. - No Web Storage or browser-owned globals: no
localStorage,sessionStorage,location,matchMedia,requestAnimationFrame. - No React component rendering or hook execution.
- No MSW / network interception: nothing that relies on the
serverstarted invitest.setup.ts. - Nothing from
vitest.setup.tsat all β the Node project loads no setup file, so a suite that depends on one of its stubs (for example theVITE_SESSION_API_KEYenv stub) belongs in jsdom.
Then add the suite's path to NODE_ENV_PILOT_TESTS in vite.config.ts and run
it. Passing under the Node project is the confirmation; a ReferenceError
naming a browser global means the suite belongs in jsdom.
Keep the list explicit rather than glob-based: a glob would silently adopt new suites that have never been checked against the rules above.
An individual suite can also opt into Node with a // @vitest-environment node
docblock, which several __tests__/scripts/ suites already do. That still
loads vitest.setup.ts; the Node project is for suites that need no setup at
all.
Rolling back
The pilot is contained in one config block and unwinds in stages:
One suite misbehaves β remove its path from
NODE_ENV_PILOT_TESTS. It returns to the jsdom project automatically, because that project excludes exactly this list.Revert the split entirely β empty
NODE_ENV_PILOT_TESTS, then replacetest.projectswith the previous flat options:environment: "jsdom", setupFiles: ["vitest.setup.ts"], exclude: [...configDefaults.exclude, "tests"],
No test file changes are needed either way: the pilot suites are unmodified and
pass in both environments. The expectations in __tests__/vite-config.test.ts
describe the split, so remove them in the same commit as a full revert.
Mutation testing
Stryker checks whether the Vitest suite detects deliberate changes to the
first-party TypeScript source under src/. The default configuration excludes
tests, declarations, generated files, fixtures, mocks, and development seeds.
# Full mutation run (expensive for the whole frontend)
npm run test:mutation
# Reuse results from the previous run
npm run test:mutation:incremental
# Mutate only production files changed from the local main branch
npm run test:mutation:diff
# Compare with another base ref, such as the latest remote main
npm run test:mutation:diff -- origin/main
The HTML report is written to reports/mutation.html. Mutation scores are
report-only initially; establish a stable baseline before adding a failing
threshold.
Stryker does not cover the small Python surface in this repository; mutating it would need a Python test harness and Python-specific mutation tool.
Design doc for non-trivial PRs
For a non-trivial PR β a new or changed public API, a new subsystem, a behavior change in core logic, or a migration β a reviewer often has to reconstruct the design from the diff alone. That is slow. You are encouraged (not required) to add a short design doc so reviewers grasp the proposal at a glance.
The convention:
Write a self-contained HTML page (inline CSS/SVG, opens by double-click) that covers the code/API design and a before/after of your change, grounded to the actual code. Keep it static, with no scripts: htmlpreview runs the page in the reviewer's browser.
Commit it under the temporary
.pr/directory, e.g..pr/design.html. This directory is for temporary PR-only artifacts. For both same-repository and fork PRs, it is removed automatically after the PR merges tomain, through a cleanup PR opened or updated by.github/workflows/pr-artifacts.yml. Approval leaves review artifacts available and avoids rerunning CI solely for their removal.Link it near the top of the PR description via htmlpreview, at the commit that contains the page (
git rev-parse HEADafter you push it):https://htmlpreview.github.io/?https://github.com/<your-fork>/<repo>/blob/<commit-sha>/.pr/design.htmlUse the commit SHA, not the branch name. Post-merge cleanup removes
.pr/frommain, and PR branches may be deleted; a SHA link keeps resolving. Refresh the link when the page changes substantively.
Keep the essentials in the PR description as well: the intent, the important before/after behavior or API shape, compatibility and risk, and code references. The page adds detail.
Skip this for trivial PRs (a typo, a one-line guard, a dependency bump) β there, a design doc is just noise. htmlpreview only works for public repos and self-contained pages.
The pr-design-doc skill can generate the page
for you.
CSS isolation and host-app customization
The standalone app and the exported provider/root wrapper now scope all bundled CSS under a dedicated shell element with the data-agent-server-ui attribute. That means Tailwind utilities, HeroUI component styles, xterm styles, and local CSS only apply inside the OpenHands UI subtree instead of leaking into a host app.
Embedding strategy
Load the Canvas stylesheet once in the host app, next to the component imports:
import "@openhands/agent-canvas/styles.css"; import { AgentServerUIProviders } from "@openhands/agent-canvas";npm run build:libemits it asdist/styles.css. It holds the Tailwind, HeroUI, xterm, and app CSS for every exported component, scoped under[data-agent-server-ui], and it@imports the Outfit and IBM Plex Mono fonts from Google Fonts. The JavaScript entries do not import it, so a host without a CSS loader (server rendering, tests) can still import the components. Without the stylesheet the components render unstyled andstyleOverrideshas no visible effect.Use
AgentServerUIProvidersin host apps. It renders a scoped style root by default.For direct wrapper control, use
AgentServerUIRoot.The standalone app opts out of the provider wrapper because the router layout already renders the scoped root.
Customization strategy
Theme and surface tokens are exposed as CSS custom properties on the scoped root. You can override them either through the provider/root styleOverrides prop or with host CSS targeting [data-agent-server-ui].
<AgentServerUIProviders
styleOverrides={{
"--oh-color-base": "#101820",
"--oh-color-content-2": "#f5f7ff",
"--oh-accent": "#8b5cf6",
}}
>
<App />
</AgentServerUIProviders>
If you want Tailwind layout utilities on the inner themed container, pass contentClassName instead of className, because the outer scope element is what all generated selectors key off of.
Environment variables
You can create a .env file in the project directory with these variables based on .env.sample.
| Variable | Description | Default Value |
|---|---|---|
VITE_BACKEND_BASE_URL |
Full base URL for the agent server used by direct browser requests | current browser origin |
VITE_BACKEND_HOST |
Backend host used by the Vite dev proxy | 127.0.0.1:8000 |
VITE_SESSION_API_KEY |
(Internal) Session API key injected by the launcher β set LOCAL_BACKEND_API_KEY instead |
- |
VITE_WORKING_DIR |
Workspace path sent when starting new conversations | workspace/project |
VITE_ENABLE_BROWSER_TOOLS |
Set to false to start the agent-server with the browser tool set off |
true |
VITE_BASE_PATH |
Build/serve the SPA under a subpath such as /canvas |
/ |
VITE_MOCK_API |
Enable/disable API mocking with MSW | false |
VITE_USE_TLS |
Use HTTPS/WSS for the Vite proxy target | false |
VITE_FRONTEND_PORT |
Port to run the frontend application | 3001 |
VITE_INSECURE_SKIP_VERIFY |
Skip TLS certificate verification for proxied backend requests | false |
Cloud organization recovery in embedded hosts
AgentServerUIProviders leaves organization recovery off by default so the host's
login and onboarding can render before authentication. Import the public
CloudOrganizationBoundary and mount it inside the providers, after your auth
gate, around consumers that send organization-scoped requests. If the entire
provider subtree is already authenticated, use resolveCloudOrganization to
apply the same boundary automatically. Recovery fills its containing panel.
Standalone Canvas mounts the boundary after its own authentication gate.
A successful membership response repairs an inaccessible saved selection. A transient lookup failure retains a saved selection; 401/403 responses and an empty membership list show recovery instead. Background refreshes retain cached membership and user identity while the saved selection remains accessible.