CLIs

YOLO Studio ships CLI binaries inside every workspace container. They share a name prefix but do very different jobs. Treat them as separate tools — when documentation, tickets, or commit messages say “the yolo CLI”, it almost always means one specific binary.

Agent and gateway binaries

opencode-yolo: built-in coding agent CLI

opencode-yolo is the built-in coding agent — upstream opencode-ai wrapped to route through the YOLO Gateway. It opens a chat-style session (interactive) or executes one-shot tasks (headless) inside an agent lane.

Key surfaces:

• opencode-yolo — start an interactive session (straight passthrough to upstream opencode)
• Worker dispatch — when the Background Runner dispatches a card into a lane, the lane runner delivers the task prompt on stdin; the wrapper passes stdin through when no positional argv is set
• opencode-yolo’s NDJSON output is normalized into Claude-stream-json so it flows into the same tile chrome as Claude/Codex

yolo-router: LLM gateway client

yolo-router (the CLI) forwards LLM API calls to the YOLO Gateway — the yolo-router-cf Cloudflare Worker. It exists so any tool inside a workspace container — agents, scripts, ad-hoc tooling — can use a single, observed, rate-limited path to LLM providers without each tool needing its own API key.

Wiring inside a sandbox:

• YOLO_ROUTER_BASE_URL is stamped onto the sandbox at create time by the platform — it points at the gateway Worker
• YOLO_ROUTER_API_KEY is the injected YOLO_API_TOKEN (a JWT signed by auth-service)
• The gateway Worker validates the JWT with HS256 against the shared JWT_SECRET

The yolo-router binary itself is not currently baked into the published container images — its source lives at containers/base/yolo-router-cli/, but only the removed base:slim variant installed it. The gateway env vars above are still set in every sandbox, and opencode-yolo reaches the gateway over HTTP (through container-api’s local /llm/opencode/v1 proxy, or YOLO_ROUTER_BASE_URL directly) without the CLI. Check with command -v yolo-router before relying on it.

For local development outside a sandbox, export both vars manually and the CLI will work the same way.

Disambiguating in writing

When in doubt, name the binary you mean:

• “the yolo CLI” → say “the workspace CLI (yolo)” or name the agent binary (opencode-yolo, claude, codex) depending on which you mean
• “the agent” → say “opencode-yolo” (or whichever agent CLI is active) if it’s the binary, “the Worker” if it’s the role, “the agent process” if either could be Claude Code, Codex, or another registered agent
• “the LLM client” → say “yolo-router” for the CLI or “the YOLO Gateway” (the yolo-router-cf Worker) for the service it talks to

The dispatcher (Background Runner and lane runner), the agent, and the gateway are three independent layers; conflating them in conversation almost always leads to a wrong assumption about who can do what.