Runtime Capability Registry

Understand runtime capabilities and how AACWorkflow routes agents to appropriate runtimes based on features they support.

The runtime capability registry is a structured database of what each runtime can do — which AI providers it supports, which operating systems it runs on, which MCP tools it has access to, and whether it supports advanced features like skill imports and task resumption.

Why capabilities matter

When you assign an agent a task, AACWorkflow needs to know:

Which runtimes can run this agent? — A daemon running on macOS can't execute Docker tasks
Which AI providers are available? — Some runtimes have Claude, others have both Claude and Cursor
Which MCP tools are connected? — A GitHub-connected runtime can talk to GitHub; one without it cannot
Can the runtime resume tasks? — For long-running tasks, some runtimes support resuming from a checkpoint

The capability registry answers all these questions automatically.

Viewing runtime capabilities

Via the UI

Go to Settings → Runtimes
Click on a runtime to see its detail page
Scroll to Capabilities section

You'll see:

OS and architecture — Linux x86_64, macOS ARM64, etc.
Executor type — host (direct process) or docker (containerized)
AI providers — which providers are installed (Claude, Codex, Cursor, etc.)
Model selection — whether the provider supports model choice
MCP transports — how the runtime communicates with MCP servers (stdio, SSE, HTTP)
Advanced features — resume support, skill imports, etc.

Via the API

Runtime capabilities are also available in the API response for /workspaces/{ws}/runtimes/{id}:

{
  "id": "runtime-123",
  "name": "My macOS daemon",
  "capabilities": {
    "schema_version": 1,
    "os": "macos",
    "arch": "arm64",
    "executor": "host",
    "providers": [
      {
        "provider": "claude",
        "cli_version": "1.2.3",
        "model_selection": true,
        "models": ["claude-opus-4", "claude-sonnet-4"]
      }
    ],
    "mcp_transports": ["stdio", "sse"],
    "supports_resume": true,
    "supports_skill_path": true,
    "labels": ["macos", "arm64", "claude", "mcp-stdio"]
  }
}

Understanding capability fields

OS and architecture

OS — macos, linux, or windows
Arch — arm64, amd64 (x86-64), arm, or 386

This matters if your agent needs to run OS-specific scripts or tools.

Executor type

host — tasks run directly on the daemon's OS with full access
docker — tasks run in a containerized environment, more isolated

Docker runtimes are useful for sandboxing untrusted code or ensuring reproducibility.

Providers

Each provider entry shows:

Provider name — claude, codex, cursor, etc.
CLI version — the version of the AI tool installed
Model selection — whether the daemon supports choosing a specific model
Models list — which models are available (if known)

If an agent is configured to use a specific model, AACWorkflow checks this list to ensure the runtime supports it.

MCP transports

MCP (Model Context Protocol) supports multiple transport mechanisms:

stdio — communication via standard input/output (default, local)
sse — Server-Sent Events (HTTP streaming)
http — direct HTTP requests

A runtime with only stdio support can only connect to stdio-based MCP servers; it cannot use HTTP-based remote MCP servers.

Advanced features

Resume support — can the runtime pause and resume long-running tasks?
Skill path support — can the runtime load skills from local file paths in addition to the database?

Routing based on capabilities

When you assign an agent a task, AACWorkflow's router uses capabilities to find a suitable runtime:

Filter by provider — select runtimes that support the agent's configured AI provider
Filter by labels — if you've assigned labels to a task or runtime, match them
Filter by OS — if the task requires a specific OS, filter accordingly
Check advanced requirements — verify resume, skill imports, MCP transports
Pick the best match — prefer runtimes with the most spare capacity

If no runtime matches, the task is queued and waits for a suitable runtime to come online.

See Runtime labels and routing for more details on custom routing.

Labels and routing

Capabilities include a labels field — a derived set of searchable tags that the routing engine uses:

macos, linux, windows — OS
arm64, amd64 — architecture
claude, codex, cursor — providers
mcp-stdio, mcp-sse, mcp-http — MCP transports
Custom labels you assign via runtime labels

Use labels in task assignments:

assign @agent-name with label="macos" 
  because task requires macOS-specific tools

The router will then direct the task to a macOS runtime.

Updating capabilities

Capabilities are automatically detected when a daemon starts and on each heartbeat. You don't manually update them.

To refresh capabilities:

Reboot the daemon — next start refreshes all capabilities
Reconnect the daemon — stop and restart the daemon
Wait for heartbeat — heartbeats occur every 30 seconds, so changes are picked up quickly

If you install a new provider (e.g., install the Cursor CLI) on a running daemon:

Stop the daemon
Install the provider
Restart the daemon

On the next heartbeat, the new provider appears in capabilities.

Fallback behavior

If a runtime's capabilities are incomplete or malformed:

AACWorkflow degrades gracefully and treats unknown capabilities as "not supported"
The runtime still appears in the UI and is available for manual assignment
Automatic routing simply treats it as having fewer capabilities
No crashes or white-screen errors occur

This ensures backward compatibility with older daemons that may not send the full capability structure.

Best practices

Check capabilities before assigning — if you need a specific OS or provider, verify the runtime has it
Use labels for complex routing — if you have many runtimes, tag them with labels and include label requirements in task assignments
Keep daemons updated — newer daemon versions support more capabilities
Monitor for unsupported tasks — check your task queue for jobs waiting for non-existent runtimes

Next steps

Install agent runtime — set up a daemon
Runtime labels and routing — use custom labels for advanced routing
Daemon and runtimes — understand daemon and runtime architecture

On this page