23blocks-OS Agent Canvas
Create visual, interactive HTML pages that users see in the AI Maestro dashboard. Embed live data, receive structured actions when users interact, and update pages in response.
When to use this skill
Use canvas whenever the output is better experienced visually than as terminal text.
Proactive triggers -- create a canvas when:
- User asks to see data visually: "show me", "display", "visualize", "report on", "dashboard for", "chart of", "table of", "summary of"
- User asks for a form or config UI: "let me configure", "settings for", "create a form", "let me pick", "I want to choose"
- User asks for an approval or review flow: "let me approve", "review these", "I need to decide", "show me the options"
- User asks you to build something interactive: "build me a", "create a page", "make a UI", "wizard for", "control panel"
- Your output has structured data: test results, API responses, file listings, metrics, logs, comparisons -- anything that would benefit from sorting, filtering, or visual hierarchy
- Your output has actions the user should take: approve/reject, select from options, configure settings, trigger operations
- You are presenting a status or progress report: build status, deployment state, system health, task progress
Do NOT use canvas for:
- Quick one-line answers
- Code that should go in a file
- Terminal commands the user should run
- Simple text responses
Default behavior: When in doubt, create a canvas. A visual, interactive page is almost always more useful than a wall of terminal text. The user can always read it in the Canvas tab of the dashboard.
Architecture: Data-Driven Interactive Pages
CRITICAL: Canvas pages must be data-driven, not static HTML.
Never hardcode data into HTML elements. Always embed data as JSON in a <script> block and render it with JavaScript. This makes pages interactive (sortable, filterable, searchable) instead of dead static text.
The pattern: Embedded JSON + JS rendering
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Test Results</title>
<style>/* styles here */</style>
</head>
<body>
<div id="app"></div>
<!-- DATA BLOCK: Embed all data as JSON -->
<script type="application/json" id="page-data">
{
"generatedAt": "2026-05-18T15:30:00Z",
"summary": { "total": 142, "passed": 135, "failed": 5, "skipped": 2 },
"tests": [
{ "name": "auth.login", "status": "passed", "duration": 230, "suite": "auth" },
{ "name": "auth.logout", "status": "passed", "duration": 45, "suite": "auth" },
{ "name": "api.users.create", "status": "failed", "duration": 1200, "suite": "api", "error": "Timeout exceeded" },
{ "name": "api.users.list", "status": "passed", "duration": 89, "suite": "api" }
]
}
</script>
<!-- RENDER LOGIC: JavaScript reads the data and builds the UI -->
<script>
const DATA = JSON.parse(document.getElementById('page-data').textContent);
// State
let filter = 'all';
let sortBy = 'name';
let sortDir = 'asc';
let search = '';
function render() {
let tests = [...DATA.tests];
// Filter
if (filter !== 'all') tests = tests.filter(t => t.status === filter);
if (search) tests = tests.filter(t => t.name.toLowerCase().includes(search.toLowerCase()));
// Sort
tests.sort((a, b) => {
const val = a[sortBy] > b[sortBy] ? 1 : -1;
return sortDir === 'asc' ? val : -val;
});
const app = document.getElementById('app');
app.innerHTML = `
<h1>Test Results</h1>
<p class="subtitle">Generated ${new Date(DATA.generatedAt).toLocaleString()}</p>
<div class="summary">
<div class="stat">${DATA.summary.total} <span>Total</span></div>
<div class="stat good">${DATA.summary.passed} <span>Passed</span></div>
<div class="stat bad">${DATA.summary.failed} <span>Failed</span></div>
<div class="stat skip">${DATA.summary.skipped} <span>Skipped</span></div>
</div>
<div class="controls">
<input type="text" placeholder="Search tests..." value="${search}"
= this.value; render()" />
<select = this.value; render()">
<option value="all" ${filter === 'all' ? 'selected' : ''}>All</option>
<option value="passed" ${filter === 'passed' ? 'selected' : ''}>Passed</option>
<option value="failed" ${filter === 'failed' ? 'selected' : ''}>Failed</option>
<option value="skipped" ${filter === 'skipped' ? 'selected' : ''}>Skipped</option>
</select>
</div>
<table>
<thead>
<tr>
<th sortDir = sortDir === 'asc' ? 'desc' : 'asc'; render()">Test</th>
<th sortDir = sortDir === 'asc' ? 'desc' : 'asc'; render()">Suite</th>
<th sortDir = sortDir === 'asc' ? 'desc' : 'asc'; render()">Status</th>
<th sortDir = sortDir === 'asc' ? 'desc' : 'asc'; render()">Duration</th>
</tr>
</thead>
<tbody>
${tests.map(t => `
<tr class="${t.status}">
<td>${t.name}</td>
<td>${t.suite}</td>
<td><span class="badge ${t.status}">${t.status}</span></td>
<td>${t.duration}ms</td>
</tr>
`).join('')}
</tbody>
</table>
${tests.length === 0 ? '<p class="empty">No tests match your filters.</p>' : ''}
`;
}
render();
</script>
</body>
</html>
Why this pattern matters
| Approach | Result |
|---|---|
Static HTML <table> with hardcoded rows |
Dead page. User can only read. No sorting, no filtering, no search. |
| Embedded JSON + JS rendering | Interactive page. User can sort columns, filter by status, search by name. Same data, 10x more useful. |
Data block rules
- Always use
<script type="application/json" id="page-data">for the data block. This prevents execution and is parseable. - Put ALL data in one JSON block. Don't scatter data across multiple variables.
- Include metadata in the data: timestamps, totals, source info. The page should explain itself.
- Keep the render function pure. It reads from
DATA+ state variables, rebuilds the DOM. No side effects. - Make every list sortable and filterable. If you have 5+ items, add search. If items have categories/statuses, add a filter dropdown. If items have numeric fields, make columns sortable.
Data block examples by content type
API response data:
<script type="application/json" id="page-data">
{
"endpoint": "/api/v1/users",
"method": "GET",
"status": 200,
"responseTime": 142,
"headers": { "content-type": "application/json", "x-request-id": "abc123" },
"body": { "users": [...], "total": 50, "page": 1 }
}
</script>
File listing / directory tree:
<script type="application/json" id="page-data">
{
"root": "/Users/project/src",
"totalFiles": 42,
"totalSize": 284000,
"files": [
{ "path": "index.ts", "size": 1200, "modified": "2026-05-18T10:00:00Z", "type": "typescript" },
{ "path": "utils/helpers.ts", "size": 3400, "modified": "2026-05-17T09:00:00Z", "type": "typescript" }
]
}
</script>
Metrics / monitoring:
<script type="application/json" id="page-data">
{
"collectedAt": "2026-05-18T15:30:00Z",
"services": [
{ "name": "api-gateway", "status": "healthy", "uptime": 99.97, "latency": 45, "requests": 12400 },
{ "name": "auth-service", "status": "degraded", "uptime": 98.5, "latency": 230, "requests": 8200 }
],
"alerts": [
{ "id": "a1", "severity": "warning", "message": "Auth latency above threshold", "since": "2026-05-18T14:00:00Z" }
]
}
</script>
Comparison / diff data:
<script type="application/json" id="page-data">
{
"left": { "label": "v1.2.0", "date": "2026-05-10" },
"right": { "label": "v1.3.0", "date": "2026-05-18" },
"changes": [
{ "file": "src/auth.ts", "type": "modified", "additions": 42, "deletions": 15 },
{ "file": "src/new-feature.ts", "type": "added", "additions": 120, "deletions": 0 }
],
"summary": { "filesChanged": 12, "additions": 340, "deletions": 89 }
}
</script>
Interactive features to always include
| Data shape | Interactive features |
|---|---|
| List/table (5+ rows) | Sort by columns, search, filter by category/status |
| Metrics/numbers | Color coding (green/yellow/red), thresholds, visual bars |
| Status items | Filter by status, group by category, dismiss/acknowledge buttons |
| Timeline/log entries | Newest-first sort, search, level filter (info/warn/error) |
| Config/settings | Editable fields, save button via maestro.send('submit', ...) |
| Approval items | Approve/reject buttons via maestro.send('click', ...), comment field |
Combining data + actions
Pages can be both data-driven AND interactive with maestro.send():
<script type="application/json" id="page-data">
{
"pendingApprovals": [
{ "id": "pr-42", "title": "Add OAuth support", "author": "alice", "files": 8, "additions": 340 },
{ "id": "pr-43", "title": "Fix login bug", "author": "bob", "files": 2, "additions": 15 }
]
}
</script>
<script>
const DATA = JSON.parse(document.getElementById('page-data').textContent);
function render() {
document.getElementById('app').innerHTML = DATA.pendingApprovals.map(pr => `
<div class="card">
<h3>${pr.title}</h3>
<p>by ${pr.author} | ${pr.files} files | +${pr.additions}</p>
<div class="actions">
<button class="approve" 'approve', ${JSON.stringify(pr)})">Approve</button>
<button class="reject" 'reject', { id: '${pr.id}' })">Reject</button>
</div>
</div>
`).join('');
}
render();
</script>
Your Canvas Directory
Every agent has a canvas directory where HTML files are stored:
~/.aimaestro/agents/<your-agent-id>/canvas/
├── dashboard.html # Your pages go here
├── reports/
│ └── weekly.html # Subdirectories supported
└── interactions/ # User actions land here (auto-created)
└── 2026-05-18T15-30-00-000Z-uuid.json
Find your agent ID:
# From environment (set by AI Maestro)
echo $AIM_AGENT_ID
# Or find it in the registry
cat ~/.aimaestro/agents/registry.json | jq '.agents[] | select(.name == "your-agent-name") | .id'
Creating Canvas Pages
Write self-contained HTML files to your canvas directory. The dashboard renders them in a sandboxed iframe with the Canvas tab.
cat > ~/.aimaestro/agents/$AIM_AGENT_ID/canvas/page.html << 'HTMLEOF'
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Page Title</title>
<style>
* { margin: 0; padding: 0; box-sizing: border-box; }
body { font-family: system-ui, sans-serif; background: #0f172a; color: #e2e8f0; padding: 24px; }
/* ... your styles ... */
</style>
</head>
<body>
<div id="app"></div>
<script type="application/json" id="page-data">
{ /* your data here */ }
</script>
<script>
const DATA = JSON.parse(document.getElementById('page-data').textContent);
// render logic
</script>
</body>
</html>
HTMLEOF
maestro.send() API
Use maestro.send(action, element, data) to send user interactions back to your agent. The maestro object is automatically injected by the dashboard; you don't need to define it.
maestro.send(action, element, data)
| Parameter | Type | Required | Description |
|---|---|---|---|
action |
string | Yes | What happened (see Standard Actions below) |
element |
string | No | Which UI element was acted on (id, name, or label) |
data |
object | No | Arbitrary key-value payload |
Standard Actions
| Action | Use case | Example |
|---|---|---|
click |
Button press, link activation | maestro.send('click', 'deploy-btn', { env: 'prod' }) |
submit |
Form submission | maestro.send('submit', 'config-form', { name: 'api', timeout: 30 }) |
change |
Input value changed | maestro.send('change', 'search-input', { value: 'query text' }) |
select |
Option selected | maestro.send('select', 'priority', { value: 'high' }) |
toggle |
Boolean switch | maestro.send('toggle', 'dark-mode', { enabled: true }) |
dismiss |
Modal/alert dismissed | maestro.send('dismiss', 'alert-42', { acknowledged: true }) |
navigate |
Tab/page switch in canvas | maestro.send('navigate', 'settings-tab', { tab: 'advanced' }) |
custom |
Anything else | maestro.send('custom', 'drag-drop', { from: 'A', to: 'B' }) |
Custom actions beyond this list are fine. The action field is freeform.
Canvas Rules
HTML must be self-contained:
- Inline all CSS (in
<style>tags or inline styles) - Inline all JavaScript (in
<script>tags or inline handlers) - Embed images as base64 data URIs or use emoji/Unicode
- No external stylesheets, scripts, or images (CDN links will be blocked by the sandbox)
- No relative asset paths
The iframe sandbox allows allow-scripts only:
- JavaScript works
- No form submission to external URLs (use
event.preventDefault()+maestro.send()) - No popups, no same-origin access, no top-level navigation
- No
alert(),confirm(), orprompt()(use in-page UI instead)
Managing Canvas Files
Organize with subdirectories
mkdir -p ~/.aimaestro/agents/$AIM_AGENT_ID/canvas/reports
mkdir -p ~/.aimaestro/agents/$AIM_AGENT_ID/canvas/forms
mkdir -p ~/.aimaestro/agents/$AIM_AGENT_ID/canvas/dashboards
List files (API)
curl -s http://localhost:23000/api/agents/$AIM_AGENT_ID/canvas
Returns:
{
"files": [
{ "name": "dashboard.html", "path": "dashboard.html", "size": 4200, "modifiedAt": "2026-05-18T15:00:00.000Z" },
{ "name": "weekly.html", "path": "reports/weekly.html", "size": 8100, "modifiedAt": "2026-05-18T14:00:00.000Z" }
]
}
Read a file (API)
curl -s "http://localhost:23000/api/agents/$AIM_AGENT_ID/canvas?file=dashboard.html"
Update a file
Overwrite it. The dashboard picks up changes when the user refreshes or re-selects the file.
Delete a file
rm ~/.aimaestro/agents/$AIM_AGENT_ID/canvas/old-page.html
Delete all interactions (clean slate)
rm -f ~/.aimaestro/agents/$AIM_AGENT_ID/canvas/interactions/*.json
Receiving Interactions
When a user interacts with your canvas page, two things happen:
- JSON file stored at
~/.aimaestro/agents/<id>/canvas/interactions/<timestamp>-<uuid>.json - Terminal notification appears in your session:
[CANVAS] file.html: User action 'element' on file.html with data: {...}
Interaction file format
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"timestamp": "2026-05-18T15:30:00.000Z",
"canvasFile": "dashboard.html",
"action": "submit",
"element": "approve-button",
"data": { "comments": "Looks good", "rating": 5 },
"summary": "User submit 'approve-button' on dashboard.html with data: {\"comments\":\"Looks good\",\"rating\":5}"
}
Reading interactions
# List all interaction files (newest first)
ls -1r ~/.aimaestro/agents/$AIM_AGENT_ID/canvas/interactions/
# Read the most recent interaction
ls -1r ~/.aimaestro/agents/$AIM_AGENT_ID/canvas/interactions/ | head -1 | \
xargs -I{} cat ~/.aimaestro/agents/$AIM_AGENT_ID/canvas/interactions/{}
# Read all interactions via API
curl -s http://localhost:23000/api/agents/$AIM_AGENT_ID/canvas/interactions
# Read with limit
curl -s "http://localhost:23000/api/agents/$AIM_AGENT_ID/canvas/interactions?limit=10"
Processing [CANVAS] notifications
When you see a [CANVAS] notification, you should act on it. The notification format is:
[CANVAS] <canvasFile>: User <action> '<element>' on <canvasFile> with data: {<json>}
Your workflow:
- Parse the notification or read the latest interaction file for full details
- Decide what to do based on action type + element + data
- Execute the action (run commands, update files, call APIs, send AMP messages, etc.)
- Optionally update the canvas page to reflect the new state
Response patterns by action type
click -- Execute the operation the button represents:
[CANVAS] panel.html: User click 'run-tests' on panel.html with data: {"suite":"unit"}
-> Run the test suite, then update the canvas with results
submit -- Process the form data:
[CANVAS] config.html: User submit 'config-form' on config.html with data: {"endpoint":"https://api.example.com","timeout":30}
-> Save the configuration, confirm success on canvas
select -- Apply the selection:
[CANVAS] dashboard.html: User select 'time-range' on dashboard.html with data: {"value":"7d"}
-> Regenerate the dashboard with 7-day data, update canvas
toggle -- Enable or disable the feature:
[CANVAS] settings.html: User toggle 'auto-deploy' on settings.html with data: {"enabled":true}
-> Enable auto-deploy in your configuration
dismiss -- Acknowledge and clean up:
[CANVAS] alerts.html: User dismiss 'alert-memory' on alerts.html with data: {"acknowledged":true}
-> Mark alert as seen, no further action needed
Security
- Never put credentials, tokens, or secrets in
datapayloads (stored as plaintext JSON) - Canvas files are writable only by the agent, read-only to the user via the dashboard
- File paths must not contain
..or be absolute (path traversal protection enforced by the API) - The
datafield is stored as-is; sanitize if displaying user-provided data back in HTML
Quick Reference
| Task | Command |
|---|---|
| Create a page | cat > ~/.aimaestro/agents/$AIM_AGENT_ID/canvas/page.html << 'HTMLEOF' ... HTMLEOF |
| Create a subdirectory | mkdir -p ~/.aimaestro/agents/$AIM_AGENT_ID/canvas/reports/ |
| List files (API) | curl -s http://localhost:23000/api/agents/$AIM_AGENT_ID/canvas |
| Read a file (API) | curl -s "http://localhost:23000/api/agents/$AIM_AGENT_ID/canvas?file=page.html" |
| Update a page | Overwrite the HTML file |
| Delete a page | rm ~/.aimaestro/agents/$AIM_AGENT_ID/canvas/page.html |
| Read interactions | ls -1r ~/.aimaestro/agents/$AIM_AGENT_ID/canvas/interactions/ |
| Read interactions (API) | curl -s http://localhost:23000/api/agents/$AIM_AGENT_ID/canvas/interactions |
| Clear interactions | rm -f ~/.aimaestro/agents/$AIM_AGENT_ID/canvas/interactions/*.json |
| Fire action from HTML | maestro.send('click', 'btn-name', { key: 'value' }) |
Protocol Reference
Full AAP specification: https://agentactions.org GitHub: https://github.com/agentmessaging/agent-actions