> ## Documentation Index
> Fetch the complete documentation index at: https://vida.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Computer Agent Canvas

> Edit, publish, open, and verify a Computer Agent Canvas through the API.

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:

```text theme={null}
/api/v2/computer/accounts/{targetAccountId}
```

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

<Note>
  For executable workspace request patterns and operating rules, use the [Vida API Skill](/docs/api-reference/vida-api-skill).
</Note>