Agents, teams & canvas

This page covers the three Orchestration routes that define who does the work and how you watch it happen: the Agents page (the registry of agent personas), the Teams page (delegation topologies that group agents), and the Canvas page (a live, agent-driven visual workspace). All three live under the Orchestration section of the dashboard sidebar and talk to the gateway over the same bearer-authenticated REST and WebSocket API.

Use this page when you want to author agents and teams through the UI rather than scripting them. For the raw REST surface behind these screens, see Agents, skills & teams API. For the conceptual model, see Agents, teams & swarms.

Agents page

Navigate to /agents to manage your agent registry. The page is a three-pane layout: a searchable list on the left, the selected agent’s profile in the centre, and an inspector on the right. The toolbar holds Create and Refresh.

The identity / soul model

Every agent is a persona, not just a model name. An agent definition carries these fields:

Field	Required	Meaning
name	yes	Human-readable label. Slugified into the agent’s item_name (used by workflow YAML assign:).
identity	yes	Who the agent is — e.g. “A pragmatic senior Rust engineer.” Also shown as the identity seed in the prompt tab.
soul	yes	Core personality and philosophy — the agent’s disposition and values.
expertise	no	Focused areas, entered comma-separated and rendered as chips (e.g. rust, async, performance).
tone	no	Communication style — e.g. “concise and direct.”
role	no	One of coder, reviewer, researcher. Drives the list role filter.
agent_type	no	The execution backend (see below).
model	no	Optional model override; blank means the configured default.
system_hint	no	Extra prompt context appended at runtime.

name, identity, and soul are the only required fields — the Save button stays disabled until all three are filled.

Agent types

The agent_type dropdown selects which coding backend the agent runs on. The dashboard exposes five:

Value	Label in UI
claude	Claude
codex	Codex
agy	Antigravity (agy)
agent	Cursor (agent)
opencode	OpenCode (opencode)

The stats strip on the profile counts the total registry size, the active (non-deprecated) count, and the number of codex-type agents.

Browse and filter

The list pane supports live filtering:

• Search matches against name, identity, soul, and expertise in real time.
• Role filter narrows to coder, reviewer, or researcher (or all roles).
• The Filter toggle shows or hides deprecated agents — deprecated agents are listed at reduced opacity when shown.

Click any agent to open its profile. The profile hero shows the avatar, name, role / agent_type / model line, and an active / disabled status pill. Below it, the identity, soul, and expertise sections, plus a voice card with the tone, revision number, and created date.

The inspector on the right has two tabs:

• Summary — the structured fields (name, role, type, model, tone, revision, created).
• Prompt — the raw system_hint and the identity text used as the identity seed, rendered in monospace.

Create or edit an agent

1. Click Create (or Edit on a selected agent) to open the editor modal.

2. Fill in name, identity, and soul (required), plus optional tone, role, type, model, expertise, and system hint.

3. Optionally upload a profile image. PNG, JPEG, or WebP only.

4. Click Save. The dashboard sends the create/update request, then — if you picked a new avatar — uploads it as a separate call.

Note

Avatar upload is a second API call (POST /api/agents/avatar) that runs after the agent is created or updated. The returned avatar_url is an HMAC-signed, time-limited workspace URL, so the image renders without exposing the filesystem. See the API reference for size and format limits.

From a selected agent’s profile you can also Edit, Deprecate / Re-enable (a soft toggle that hides it from the default list), or Delete (permanent — prefer deprecation to disable an agent).

REST endpoints behind the page

Method	Path	Purpose
GET	/api/agents?include_deprecated=true&page=1&per_page=200	List the full registry.
POST	/api/agents	Create an agent (AgentCreateRequest).
PUT	/api/agents/<kref>	Update an agent.
POST	/api/agents/avatar	Upload an avatar (multipart: kref, file).
POST	/api/agents/deprecate	Toggle the deprecated flag.
DELETE	/api/agents/<kref>	Permanently delete the agent.

All routes require Authorization: Bearer <token>. Full request/response shapes are documented in Agents, skills & teams API.

Teams page

Navigate to /teams to group agents into delegation topologies. A team is a set of agent members plus directed edges that describe how they relate. The layout mirrors the Agents page: a team list on the left, the selected team’s topology in the centre, and a member/summary inspector on the right.

Deep-link to a specific team with ?team=<kref_or_name>, and to a specific member with ?member=<kref>. Both are written back into the URL as you click, so a team-plus-member view is shareable.

The member + edge model

• Members are agent krefs pulled from the agent registry.
• Edges are directed relationships between two members. There are three edge types:

Edge type	Meaning
REPORTS_TO	The source member reports to the target (delegation hierarchy).
SUPPORTS	The source member supports the target (collaboration).
DEPENDS_ON	The source member depends on the target’s output.

The team stats strip shows the member count, the edge count, and the status (active / deprecated).

TeamTopologyPanel

The centre pane renders the TeamTopologyPanel — an auto-laid-out graph (built on @xyflow/react) where each node is a team member and each edge is a typed relationship. Edges are drawn with directional arrowheads and per-type styling (colour and dash pattern), and labelled with the edge type. Click any member node to select it; the inspector switches to the Member tab showing that member’s kref, role, and skills, with a link back to the agent registry.

The inspector’s other tab, Summary, shows the full team metadata.

Build a team with delegation edges

1. Click Create to open the team editor (or Edit the selected team).

2. Set the team name and an optional description, and optionally upload a team avatar (PNG, JPEG, or WebP).

3. In Members, tick the agents to include. Each card shows the agent’s avatar, role, type, and identity.

4. In Edge authoring, pick a from member, a to member, an edge type, and click Add edge. The live topology preview updates as you add members and edges, and a draft summary tracks member and edge counts.

5. Click Save. The button stays disabled until the team has a name and at least one member.

Tip

You can only draw an edge between two members you have already added, and the editor prunes any edge whose endpoints leave the member list. The gateway also validates the graph on save and rejects self-edges, dangling references, reciprocal DEPENDS_ON pairs, and dependency cycles — see Edge validation for the full rule set.

From the selected team you can Edit, Deprecate / Re-enable, or Delete. As with agents, deprecation is a reversible soft toggle and delete is permanent.

REST endpoints behind the page

Method	Path	Purpose
GET	/api/teams?include_deprecated=true&page=1&per_page=50	List teams (summary fields only).
GET	/api/teams/<kref>	Fetch one team with resolved members and edges.
POST	/api/teams	Create a team.
PUT	/api/teams/<kref>	Update a team (reconciles members and edges).
POST	/api/teams/avatar	Upload a team avatar (multipart).
POST	/api/teams/deprecate	Toggle the deprecated flag.
DELETE	/api/teams/<kref>	Delete the team.

The list endpoint returns only summary counts; the dashboard fetches a single team to populate the topology graph and member inspector.

Canvas page

Navigate to /canvas to watch the live streaming visual workspace. Agents push rendered frames — HTML, SVG, Markdown, or text — to a named canvas, and every connected browser tab subscribed to that canvas sees each frame instantly. This is Revka’s A2UI (agent-to-UI) surface; the dashboard is one subscriber.

The page has three columns: a control column on the left, the live viewport in the centre, and a frame history strip on the right.

Subscribing to a canvas

The dashboard opens a WebSocket per canvas. The default canvas, named default, is pre-selected on load.

ws[s]://<host><base>/ws/canvas/<canvas_id>?token=<jwt>

The browser also passes the token as the bearer.<token> subprotocol alongside the revka.v1 channel subprotocol, since browsers cannot set an Authorization header on a WebSocket:

const ws = new WebSocket(
  "wss://host/ws/canvas/default?token=" + token,
  ["revka.v1", "bearer." + token],
);

To watch a different canvas, type its ID into the control input and click Switch (or press Enter). The control column also lists every active canvas — fetched from GET /api/canvas and refreshed every 5 seconds — so you can click one to subscribe. A connection pill shows connected / disconnected, and Reconnect re-opens the socket.

Live canvas frames

Each frame the server pushes arrives as a JSON message:

{
  "type": "frame",
  "canvas_id": "default",
  "frame": {
    "frame_id": "f1a2b3c4-...",
    "content_type": "html",
    "content": "<h1>Build status</h1><p>Green</p>",
    "timestamp": "2026-06-18T12:00:00Z"
  }
}

The viewport renders the current frame inside a sandboxed iframe (sandbox="allow-scripts"). How the content is wrapped depends on content_type:

content_type	Rendered as
html	Raw HTML, displayed directly in the iframe.
svg	Centred in the iframe viewport on the theme background.
markdown	Escaped and shown as preformatted text.
text	Escaped and shown as monospaced preformatted text.
clear	A control signal that wipes the current frame and history.
eval	Not rendered as a document.

The centre panel surfaces the active canvas ID, connection state, current frame type, last update time, and the current frame ID.

Note

The dashboard keeps the most recent 50 frames in memory on the client. Canvas state is not persisted across daemon restarts — it lives in the gateway’s in-memory canvas registry. See Realtime: WebSocket, SSE & Live Canvas for the server-side frame protocol, content-type allowlist, and size limits.

Frame history and clearing

The right-hand history strip lists recent frames newest-first, each showing its content type, timestamp, short frame ID, and a content preview. Click any entry to re-display that frame in the viewport. Toggle the strip with Show / Hide.

Clear sends DELETE /api/canvas/<canvas_id>, which wipes the canvas server-side; the viewport and local history reset. A clear frame from the server has the same effect.

How agents push to a canvas

Agents do not call the canvas REST API directly — they use operator tools:

• render_canvas pushes a new frame to a named canvas.
• clear_canvas clears a canvas.

When a chat message carries page_context: "canvas", the agent is instructed to draw output with render_canvas instead of describing it in prose. See Realtime: WebSocket, SSE & Live Canvas for the agent-side tools and the POST /api/canvas/:id push endpoint.

REST endpoints behind the page

Method	Path	Purpose
GET	/api/canvas	List active canvas IDs → { "canvases": ["default", ...] }.
DELETE	/api/canvas/<canvas_id>	Clear / delete a canvas.

Related pages

Agents, skills & teams API The full REST surface — request/response shapes, kref semantics, avatar limits, and edge validation.

Realtime: WebSocket, SSE & Live Canvas The server-side canvas frame protocol, content-type allowlist, and the render_canvas tool.

Agents, teams & swarms The conceptual model behind agent personas, teams, and delegation.

Workflows, editor & runs Reference agents (assign:) and teams (team:) from workflow steps.

Spawning & coordinating agents Orchestrate multiple agents at runtime once your registry and teams are defined.

Run the dashboard Start the gateway, pair a device, and orient yourself in the navigation.