kandev/apps/backend/internal/mcp/canvasskill/files/references/manifest.md

Canvas manifest

Publish one manifest.yaml file at the root of the source directory returned by create_canvas_kandev. Canvas packages use the current Kandev plugin manifest schema, with api_version: 2. A static canvas package has no base_url or managed backend endpoints.

This is a complete minimal example. The example uses a nested entry to show that files next to the entry document can use normal relative URLs.

id: example-canvas
api_version: 2
version: 1.0.0
display_name: Example canvas
description: A small task canvas.
author: Canvas author
min_kandev_version: "0.94.0"
ui:
  web_apps:
    - key: main
      title: Example canvas
      entry: ui/index.html
      placements:
        - task-canvas
        - workspace-canvas
      network_origins:
        - https://api.example.com
capabilities:
  api_read:
    - tasks
    - workflows
  api_write:
    - tasks
    - messages
  events:
    - task.updated
  state: true

distribution:
  schema_version: 1
  kind: canvas
  license: MIT
  source_mode: static

The host parses YAML and calls the same manifest validator used for plugin registration. Required identity fields are id, api_version, version, display_name, description, and author. api_version must be 1 or 2; new canvases must use 2.

ui.web_apps contains one or more applications. Each application requires a lowercase key, a title, a clean package-relative entry, and at least one placement. A placement is task-canvas or workspace-canvas. The package may contain ui/index.html, ui/app.js, and ui/app.css; references such as ./app.js resolve beside ui/index.html. Do not use absolute paths, .., symlinks, or a path below _kandev.

network_origins contains exact HTTPS origins only. Do not add a path, wildcard, credentials, query, or fragment. A new owner-created task canvas can receive its declared exact origins in its first release through the initial permission policy. Imported packages and later permission increases need an approved grant before the release can run. Network requests go directly from the sandboxed browser to the approved origin. If a release, grant, archive, or canvas authority changes, the host immediately tears down the old iframe, so the old direct requests cannot continue under the old binding.

Capabilities are declarations, not grants. Use api_read for tasks and workflows, api_write for tasks and messages, events for event subscriptions, and state: true for instance state. The first owner-authorized release can receive only its declared supported permissions, with Kandev data limited to the current workspace. The canvas remains placed in its creating task until promotion. Imported packages and later permission increases need human review. Request only the capabilities used by the application.

The package must include the declared entry document and every local asset it references. Bundle executable dependencies. A build tool, package manager, or network build step is not available when the canvas runs.

The host injects a reserved startup bootstrap into the entry document before authored scripts. It checks document startup and relative context access. Keep the entry valid HTML so the host can insert the bootstrap without changing the stored package. The host waits up to 15 seconds for the startup acknowledgement and exposes retry controls outside the frame when startup fails.

Portable distribution

Use the distribution block when the canvas is intended for bundle, source, or registry sharing. kind must be canvas, schema_version must be 1, and source_mode must be static or project. Include a non-empty license value and a compatible min_kandev_version in the manifest.

The package must include README.md and generated checksums.txt. A project source mode package retains the editable project in distribution/source/manifest.yaml and distribution/source/README.md. Static source mode does not include that subtree. Keep source files bounded and free of secrets. The host rejects native plugin contributions, backend executables, unsafe paths, and unsupported files in a portable canvas.

Registry screenshots are not package inputs. Add ordered preview objects to the registry entry later. The first preview is the cover, canvas entries require one to eight previews, and plugin entries may omit previews.