Guides / AI agents / Agent compatibility
Agent compatibility
What kosa8 does for each AI coding agent and MCP client. The same table is printed by
kosa8 agent compat, shown in the desktop app under Agents & skills, and in the kosa8 Cloud
dashboard, all generated from the code that does the work.
What each column means
- Sandbox: a built-in kit runs the agent in a kosa8 microVM with
kosa8 agent run KIT(or headless withkosa8 prompt -a KIT). It sees one folder, and reaches only the hosts the kit allows. The agent's CLI is installed from npm, pinned to one version and its tarball digest. - Key brokered: the agent's API key stays on your computer, in the sandbox's egress broker. The sandbox holds a placeholder that only works through that broker (Keep API keys out).
- Checked calls: before each tool call runs, the agent's own hook asks the broker, and the kosa8 rules allow it, flag it, hold it for you, or refuse it.
- kosa8 skill:
kosa8 skill install AGENTteaches the agent when to use a sandbox. - MCP:
kosa8 mcp install CLIENTgives the agent kosa8's sandbox tools.
The matrix
| Agent or client | Sandbox (kit) | Key brokered | Checked calls | kosa8 skill | MCP |
|---|---|---|---|---|---|
| Claude Code | claude | yes | yes: PreToolUse hook in managed settings | ~/.claude/skills | claude mcp add |
| OpenAI Codex CLI | codex | yes | yes: PreToolUse hook in /etc/codex/requirements.toml, managed hooks only | ~/.agents/skills | ~/.codex/config.toml |
| Gemini CLI | gemini | yes | yes: BeforeTool hook in /etc/gemini-cli/settings.json | ~/.gemini/skills | ~/.gemini/settings.json |
| Qwen Code | qwen | yes (OpenAI-compatible) | yes: PreToolUse hook in /etc/qwen-code/settings.json | ~/.qwen/skills | ~/.qwen/settings.json |
| OpenCode | opencode | yes | yes: a tool.execute.before plugin | ~/.config/opencode/skills | ~/.config/opencode/opencode.json |
| Crush (Charm) | crush | yes | yes: PreToolUse hook in the global crushrc | ~/.config/crush/skills | by hand |
| GitHub Copilot (CLI and VS Code) | copilot | no | no | ~/.copilot/skills | ~/.copilot/mcp-config.json |
| VS Code workspace | – | – | – | – | .vscode/mcp.json (--project) |
| Cursor | refused as shipped | – | – | .cursor/rules/kosa8.mdc | ~/.cursor/mcp.json |
| Windsurf | – | – | – | ~/.agents/skills | ~/.codeium/windsurf/mcp_config.json |
| Cline | – | – | – | ~/.cline/skills | ~/.cline/data/settings/cline_mcp_settings.json |
| Amp | – | – | – | ~/.config/amp/skills | ~/.config/amp/settings.json |
| Goose | – | – | – | ~/.agents/skills | ~/.config/goose/config.yaml |
| Kilo Code | – | – | – | ~/.kilo/skills | ~/.config/kilo/kilo.json |
| Factory Droid | – | – | – | ~/.factory/skills | ~/.factory/mcp.json |
| Continue | – | – | – | .continue/rules/kosa8.md | .continue/mcpServers/kosa8.json (--project) |
| Zed | – | – | – | – | ~/.config/zed/settings.json (macOS, Linux) |
| Claude Desktop | – | – | – | – | claude_desktop_config.json |
| JetBrains AI Assistant | – | – | – | – | settings dialog; kosa8 mcp install jetbrains prints what to paste |
Agents without checked calls still get everything else in their row: an agent run in a kit is in the sandbox, its network is limited to the kit's hosts, and every model request through the broker is recorded. Checked calls add a decision before each call, not the boundary; the sandbox is the boundary.
How checked calls fail
The hook kosa8 installs refuses the call whenever it cannot get an answer: no broker, an error, an
answer it cannot read, or a broker slower than 25 seconds. A hook that let the call run on failure could
be switched off by breaking it. Two things the hook cannot catch are left to the agent: if the agent kills
the hook process or times it out, Codex, Gemini CLI, Qwen Code and Crush let the call run. kosa8 records
each tool call the model asked for that was never checked (sandbox.tool_call.unchecked), so
a skipped check shows up in the audit log.
The hook's settings go where each agent reads administrator settings, and the rules refuse a tool
call that writes there (K8-D002). Codex and Claude Code are also told to run managed hooks only, so a
project's settings cannot add one that answers first. Gemini CLI and Qwen Code have no such switch; Crush
has no administrator level at all, so a project .crushrc could remove the hook, and the rules
refuse writing one.
Not covered, and why
- Copilot CLI: it cannot be pointed at another API host, so its token cannot be brokered and is passed in, and with no broker there is nothing for a hook to ask.
- Cursor CLI: Cursor publishes it only as an install script that cannot be pinned.
- Aider and Goose: not published on npm, which is what kits pin today.
- Amp and Factory Droid: both need their vendor's own service and key, which have no documented base URL to broker.
- Cline CLI and Kilo Code CLI: Cline has no build for Alpine and takes its key through
cline auth; Kilo's provider base URL is not documented. Their skills and MCP setup work. - Crush MCP: Crush now keeps MCP servers in
crushrc; add kosa8 there by hand.
Importing someone else's skill
An Agent Skill is a folder with a SKILL.md and often scripts the agent is told to run.
That is code from a stranger, so kosa8 skill add reads all of it before any agent sees it.
$ kosa8 skill add github.com/OWNER/REPO/skills/pdf --dry-run
$ kosa8 skill add github.com/OWNER/REPO/skills/[email protected] -a claude-code -a codex
$ kosa8 skill ls
$ kosa8 agent run claude --skill pdf
$ kosa8 skill rm pdf- Fetch. A GitHub ref is resolved to a commit first, and the folder is read from that commit. Links, paths that climb out of the folder, and anything over 500 files or 16 MB are refused.
- Show. Every file is listed, with scripts and binaries marked, the tools the skill asks to use
without asking (
allowed-tools) and the web hosts it names. - Scan. Every shell script and every shell block in its Markdown goes through the same rule pack an agent's own commands do. Binaries, hidden or direction-changing characters, HTML comments and credential paths are reported too. Code in other languages is listed for you to read; the rules do not read it.
- Refuse. A finding at ask or deny stops the import unless you pass
--accept-findings.--digest sha256:…refuses anything but the content you expect. - Pin. The skill is kept in
~/.kosa8/skillsunder a SHA-256 of its content, and copied to each agent.kosa8 skill lssays if the stored copy or an installed copy has changed since. - Run it sandboxed.
kosa8 agent run KIT --skill NAMEmounts the pinned copy read-only in the sandbox and puts it where that agent reads skills, so its scripts run in there, not on your computer.