A CLI Agent is not a different system. It is a Yao Agent with one file added: `sandbox.yao`.
## The One Difference
In a Yao Agent, the framework calls `executeLLMStream` — the LLM processes messages and returns a completion. In a CLI Agent, the same framework calls `executeSandboxV2Stream` instead — Claude Code runs inside a container, processes the messages, and streams back output.
```
Yao Agent:
Create Hook → [ executeLLMStream ] → Next Hook
↑
LLM via connector
CLI Agent:
Create Hook → [ executeSandboxV2Stream ] → Next Hook
↑
Claude Code in container (Runner)
```
Everything else is unchanged:
- Hook signatures are identical (`Create`, `Next`)
- `ctx.memory.*`, `ctx.mcp.*`, `ctx.agent.*`, `ctx.llm.*` all work
- MCP tools, prompt presets, delegation — all the same
- `payload` in Next Hook has the same shape
## How It Activates
The framework detects `sandbox.yao` at assistant load time:
```
assistants/my-agent/
├── package.yao ← no sandbox field needed
├── prompts.yml ← optional (becomes Claude's system prompt)
├── sandbox.yao ← this file activates CLI Agent mode
└── src/
└── index.ts
```
If `sandbox.yao` is present, the framework:
1. Initializes a Computer (container or host machine)
2. Calls `Runner.Prepare()` — copies Skills, runs prepare steps, writes MCP config
3. Runs the **Create Hook** (same as Yao Agent)
4. Calls `Runner.Stream()` instead of `LLM.Stream()`
5. Runs the **Next Hook** (same as Yao Agent)
6. Calls `Runner.Cleanup()` — kills the process, cleans up session state
## The Runner Interface
The Runner is the plugin that wraps Claude Code. It implements three methods:
```
Runner.Prepare(computer, config) → set up the environment (install tools, copy files)
Runner.Stream(messages, handler) → run Claude Code, stream output back
Runner.Cleanup(computer) → kill the process, clean up session state
```
`Runner.Stream` receives the same `completionMessages` the LLM would receive — the system prompt plus full conversation history. Claude Code uses these messages to understand the task.
The currently available runner is `claude` (registered as both `claude` and `claude/cli`).
## When to Use CLI Agent
Add `sandbox.yao` when your task calls for giving the agent broad, autonomous control over a computer environment:
- **Computer use** — the agent needs to operate a desktop, browser, or GUI application
- **Sandbox isolation** — execution must be contained so the agent cannot touch the host system
- **Unrestricted permissions** — the agent needs to freely install packages, run arbitrary commands, modify the file system, and make mistakes safely
- **SKILL ecosystem** — reusable capability packs that encode specialized multi-step workflows
The framework currently supports the `claude` Runner (Claude Code). More Runners will be added in future versions.
## What's Next
Add `sandbox.yao` to your assistant.
→ **[Sandbox Configuration](./sandbox)**
