Skip to main content
Canvas is the selected Computer Agent’s static React application. Use the existing workspace APIs to edit its source and the Canvas resource to publish and open it. All routes are scoped to the Agent account:

​
Read Canvas access first

Call GET /canvas. The response identifies:
  • visibility: public, private, or off
  • sourcePath: the editable app directory
  • publishedPath: the protected generated public directory
  • publicUrl: a stable share URL only when visibility is public
  • launchRef: a complete URL for opening an available Canvas
Use launchRef.href for an authorized preview. Private launch references expire, so read the Canvas resource again when a fresh link is needed. When visibility is off, neither URL is available. The Canvas API reports the current visibility but does not change it. On a Computer shared by multiple Agents, the existing visibility setting applies across those Agent Canvases.

​
Edit source with workspace APIs

Canvas source uses the same workspace operations as other customer-authored files:
  1. List app directly with POST /workspace/list and { "path": "app" }.
  2. Read the exact source file with POST /workspace/read.
  3. Apply the smallest change with /workspace/edit, /workspace/write, or /workspace/upload.
  4. Read the changed file again.
The app directory is intentionally omitted from a root workspace listing, but direct operations under app/ are supported. Do not edit public/; it is generated output and is replaced by publish. For authored images, video, audio, or fonts, upload the file under app/ with its intended filename, reference it from the React source, and publish normally. Vida serves common web media types with their correct content type. Do not encode large media into source text or copy it into generated public/ output.

​
Publish and verify

Call POST /canvas/publish after source changes. Publishing first checks the dependencies declared by the Canvas project. It synchronizes them when package.json or package-lock.json changed, or when the build tooling is unavailable, and then runs the fixed Canvas build. Do not create a Computer Task merely to run a package install or build. Require published:true, phase:"complete", and a dependency status of ready or updated; an accepted request without those values is not completion. A dependency synchronization can update package-lock.json, so read that authored file back before another package change. A failed publish identifies either the dependencies or build phase and returns bounded, project-relative output for that phase. After publishing:
  1. Call GET /canvas again.
  2. Open launchRef.href.
  3. Verify the real page and its important interactions.
  4. Activate the exact Browser tab before diagnosing media playback, then verify representative media loads and seeks correctly.
  5. If the application calls a reusable helper or another service, test that destination effect too.
Canvas code runs in the viewer’s browser. Never place managed-secret values in Canvas source, build output, URLs, or Task context. Put authenticated or privileged work behind a skill, helper, or other server-side integration.
For executable workspace request patterns and operating rules, use the Vida API Skill.