Skip to Content
WorkspacesAgent Registry

Agent Registry

The set of coding agents a workspace can run — Claude Code, Codex, Gemini, Copilot, Aider, Goose, and the rest — is defined by a single registry shared across the platform. Adding, removing, or reconfiguring an agent is a one-entry edit — one registry, consumed by every surface that runs agents: the sandbox image, the CLIs, the container API, and the webapp’s AgentPicker.

Tiers

Every entry has a tier that determines how the agent reaches a workspace and how it shows up in the UI:

  • builtin — first-class agents, listed at the top of the AgentPicker: OpenCode via YOLO (opencode-yolo, the order-0 built-in agent — see CLIs), Claude Code, Codex, Muse Code, Gemini, Copilot, Kiro. OpenCode via YOLO, Claude Code, Codex, and Gemini are baked into the sandbox image (Gemini’s entry also carries an install block as a fallback if the bake failed). Muse Code, Copilot (the gh copilot extension — gh itself is in the image), and Kiro are not baked; their entries carry an install block and they install on demand the first time they’re launched, the same way community agents do.
  • community — third-party agents installed on demand: Aider, Goose, OpenCode, Qwen Code, Neovate, Groq Code. (OpenCode’s underlying opencode-ai package is already in the image for OpenCode via YOLO, so its install step is a fast no-op.)
  • system — internal helpers, not user-launchable from the AgentPicker (e.g. YOLO Assistant).
  • tool — disabled by default; opt-in only (e.g. the GitHub CLI as a launchable agent).

Workspace MCP access

Several agents can drive the Workspace MCP Server — inspecting workspace state, creating tiles, publishing artifacts, and managing boards — through an in- proxy that mints a fresh, per-agent token for every call. The agent never sees or manages a token; the proxy handles scoping and rotation transparently.

The -enabled set spans both tiers: Claude Code, Codex, Muse Code, Gemini, and OpenCode via YOLO among the built-ins, and Qwen Code, OpenCode, Neovate, and Goose among the community agents. Each gets its own scoped token, so you can pick the agent you prefer and still get full workspace tooling — community agents are first-class here, not a reduced tier.

Agents without MCP entries (Copilot, Kiro, Aider, Groq Code) run as ordinary terminal agents — they edit files and run commands in the sandbox, but don’t call the workspace MCP surface.

What’s in an entry

Each entry packages everything the runtime needs to launch, authenticate, monitor, and badge the agent:

  • Identity & launch — binary, defaultArgs, promptFlag, modelFlag, processPattern (used by the activity monitor to detect when the agent is running).
  • Auth — auth.method (oauth, device, apikey), auth.command, auth.headlessArgs. YoloMax reads these to drive the local credential setup flow.
  • Credentials — credentials.primaryFile, credentials.envVar, credentials.validationCheck. Container-side auth-startup-check and YoloMax both consult this to decide whether the agent is ready to use.
  • Install (every community agent, plus the built-ins that aren’t baked into the image) — install.method (npm, pip, script, custom), install.package or install.command, install.checkBinary, install.estimatedTime. Drives the install-on-demand flow described below.
  • Terminal launch — terminalLaunch.enabled gates whether the agent shows up in the interactive AgentPicker.
  • MCP — an optional mcp block lists the workspace servers and default tool scopes the agent is granted. Its presence is what makes an agent MCP-enabled (see Workspace MCP access above); agents without it run as plain terminal agents.
  • UI — ui.color, ui.icon, ui.label, ui.order.

Install on demand

Whether an agent installs on demand is driven by its install block, not its tier. There are two launch paths for an agent, and both auto-install missing binaries on first use:

  • Programmatic spawn — used whenever an agent is started programmatically (for example, dispatched into a lane). Checks the binary, runs the registry’s install config if missing, streams install output to the tile as status messages, then re-verifies and proceeds. Install failures land the tile in error with a useful message.
  • Interactive terminal pick — used by the AgentPicker tile. On first pick it bridges to a container-side install endpoint, streaming the newline-delimited install log straight into the PTY so the user watches it install in the same terminal that will then host the agent.

Community agents (and the Muse Code, Copilot, and Kiro built-ins) aren’t pre-baked into the sandbox image — both launch paths install the binary on first use, so adding one to the registry is all it takes.

Adding a new agent

  1. Add a registry entry with at minimum displayName, tier, binary, defaultArgs, promptFlag, and (for community tier) an install block. Set terminalLaunch.enabled: true if it should appear in the interactive picker.
  2. Set credentials, if any. credentials.primaryFile (e.g. ~/.config/<agent>/auth.json) tells YoloMax where to mint and rotate credentials; credentials.validationCheck lets the container know whether the agent is currently authenticated.
  3. Confirm both launch paths. Spawn the agent once programmatically and once via the interactive AgentPicker — both should hit the install path on a fresh sandbox if it’s community tier.

No sandbox-image rebuild is required for community agents; the install path handles it at runtime.

Last updated on
TilesCLIs