canvas-extension-api

Files (15)

• .claude-plugin
• .codex-plugin
• plugin.json · .plugin/
• README.md
• SKILL.md
• acceptance-checklist.md · references/
• backend-safety.md · references/
• connections.md · references/
• native-design.md · references/
• packaging-recipes.md · references/
• sidecar-pattern.md · references/
• testing-and-installation.md · references/
• v1-contract.md · references/
• validate-extension.mjs · scripts/
• validate-extension.test.mjs · scripts/

SKILL.md (first lines)

# Canvas Extensions API

Build and validate OpenHands Apps with the Canvas Extensions API, targeting the currently implemented manifest schema 1 and host API 1 routed-page ABI.

Use the naming layers consistently:

- **OpenHands Apps** - customer-facing category for interfaces people discover, install, enable, and open.
- **Apps for Agent Canvas** - product phrasing that clarifies where apps run.
- **Canvas Extensions API** - developer platform used to build apps.
- **Canvas extension package** - technical artifact containing `canvas-extension.json` and its entrypoint.
- **OpenHands Extensions** - ecosystem and repository umbrella for apps, skills, plugins, automations, and integrations.

Use current product labels in user-facing instructions: **Apps for Agent Canvas**, **Add app**, **Installed apps**, **App source**, **Enable trusted app**, and **Build an app**. Keep technical identifiers such as `canvas-extension.json`, `/api/canvas-extensions/*`, `host.extension`, and `/extensions/*` unchanged unless the target implementation changes them.

Treat apps as trusted, same-realm browser code owned by the active Agent Server. Keep the categories distinct: apps extend what people can do in Agent Canvas, plugins extend agent runtime capabilities, and skills provide agent instructions and knowledge.


## Prefer the proven App authoring loop

Treat an App as one authenticated browser dependency graph that Canvas imports from a Blob URL. Do not build a hosted SPA: the production result must be exactly one self-contained browser ESM entrypoint that exports `activate(host)`. Always ship this UI package even when it uses an optional package-owned managed backend or a manual/deployment-owned Sidecar. Make the App page the guided UI for service setup after the App is opened. Never treat a service as another browser chunk or an automatic extension install hook.

For a new App, create an independent package in the target repository and implement its own UI, tests, and build tooling. Follow the Vite library-build reference in `references/packaging-recipes.md`; do not copy a shared starter or introduce a repository-wide runtime/workspace unless the target repository explicitly requires it.

Keep all source, scripts, dependencies, tests, and checked-in `extension.js` inside the App package. Implement one declared page with explicit root, nested, and unknown-route behavior. Inject scoped CSS per mount and clean it up with framework roots, requests, listeners, timers, Workers, and object URLs. Build validation must verify `dist/extension.js` before synchronizing it to the App root. Do not synchronize an unverified artifact. Use `CHROME_PATH` when the Chrome executable is elsewhere.

For an existing App, run the reusable static gate before and after its own checks:

```sh
node /path/to/canvas-extension-api/scripts/validate-extension.mjs /path/to/app
node /path/to/canvas-extension-api/scripts/validate-extension.mjs /path/to/app --dist --marker <required-feature-marker>
```

Treat the static validator as a gate, not a replacement for the browser Blob smoke test. Read `references/packaging-recipes.md` before adding CSS, raw assets, dynamic modules, Workers, or WASM. Read `references/backend-safety.md` before any Agent Server integration or persistence. Read `references/sidecar-pattern.md` before designing a separately installed service or its onboarding. Read `references/acceptance-checklist.md` before reporting local Canvas compatibility.

## Establish the target

Start by locating the target directory instead of assuming the current workspace. Inspect repository instructions, existing package management, build tooling, tests, and git status before editing.

Make an early architecture decision: browser-only App, Agent Server-integrated App, package-owned managed-backend App, manual/deployment-owned Sidecar App, or explicitly deployment-specific App. Keep the portable host API 1 surface separate from optional Agent Server/host capabilities and deployment-owned behavior.

Use the package-owned managed-backend path only when the target stack includes the lifecycle contract from [software-agent-sdk PR #5270](https://github.com/OpenHands/software-agent-sdk/pull/5270) at `ac7b322ddf7d2e0e90a3643c5e26d848236af9a3`, the bridge contract from [PR #5272](https://github.com/OpenHands/software-agent-sdk/pull/5272) at `6d9c82973e765cce4843d6a2fb52f634efa64293`, and the host version named in `references/v1-contract.md`. Until a release containing both SDK PRs lands, those exact revisions are the minimum Agent Server implementation. Feature-detect `canvas_app_backend_bridge_v1` and `app_backend_ingress_url` through `GET /server_info`; absence is an actionable unsupported state. Do not convert manual Sidecars into managed backends unless the App owns checksum-pinned artifacts for every supported platform.

Clarify only choices that materially affect implementation:

- app purpose and page behavior;
- target repository and subdirectory;
- dependency-free JavaScript versus a bundled TypeScript/framework project;
- Agent Server endpoints or host metadata required;
- whether to build only, install locally, or prepare publication instructions;
- for a Sidecar: execution location, owner, connection route, secrets and data, lifecycle actions, and portability across Agent Canvas deployments.

Default to one app with one routed page when requirements are otherwise clear. Keep the first implementation small and dependency-free unless the requested UI clearly benefits from a framework or the repository already has a bundler.

When creating multiple Apps in one repository, give every App an independent package root containing its own `canvas-extension.json`, entrypoint, version, tests, README, and build tooling. Do not introduce a monorepo, shared runtime, or common build foundation unless the target repository explicitly requires one. Keep app manifest names globally distinct within the Agent Server installation.

Treat installation as one app per request. The current Customize -> Apps flow accepts one `source`, optional `ref`, and optional `repo_path`; it does not recursively discover or bulk-install every manifest in a repository. For a remote repository, add each app separately using the same source/ref and its own `repo_path`. For a backend-local source, select each app package directory as the source path.

Read `references/v1-contract.md` before implementing unfamiliar Canvas Extensions API behavior. Read `references/connections.md` before connecting to Agent Server, the Automation service, or WebSocket endpoints. Read `references/sidecar-pattern.md` before proposing a Sidecar bridge, onboarding, or operator action. Read `references/testing-and-installation.md` before installing or testing inside Agent Canvas, especially for a multi-app repository.

## Inspect current upstream behavior

Treat the v1 contract as young and subject to change. Before substantial work, compare the installed or target OpenHands version with the current upstream sources when access is available:

- `specs/canvas-extensions.md`
- `src/types/canvas-extension.ts`
- `src/components/features/canvas-extensions/canvas-extensions-runtime.tsx`
- `src/routes/canvas-extension-page.tsx`
- `docs/CANVAS_EXTENSIONS_TESTING.md`

Do not invent planned surfaces such as conversation tabs, slots, themes, or visualizer replacement. Implement only contributions supported by the target version. Routed pages are the only implemented contribution in host API 1.

## Create the app package

Place `canvas-extension.json` at the app package root. Point `entrypoint` to one self-contained browser ESM file inside that root.

Use this minimal manifest shape:

```json
{
  "schema_version": 1,
  "name": "example-dashboard",
  "display_name": "Example dashboard",
  "version": "0.1.0",
  "description": "A backend-specific project dashboard.",
  "entrypoint": "extension.js",
  "contributes": {
    "pages": [
      {
        "id": "dashboard",
        "title": "Dashboard",
        "path": "/dashboard",
        "nav_label": "Dashboard"
      }
    ]
  }
}
```

For an optional package-owned managed backend, add this top-level sibling of `contributes`:

```json
"backend": {
  "schema_version": 1,
  "artifacts": {
    "linux-amd64": {
      "path": "backend/linux-amd64.tar.gz",
      "sha256": "<64 lowercase hex characters>"
    },
    "linux-arm64": {
      "path": "backend/linux-arm64.tar.gz",
      "sha256": "<64 lowercase hex characters>"
    }
  },
  "argv": [
    "{artifact_dir}/bin/server",
    "--host=127.0.0.1",
    "--port={port}",
    "--data-dir={data_dir}"
  ],

From OpenHands/extensions, MIT.

More from OpenHands/extensions