Guides / AI agents / Connect an agent

Connect Claude, Cursor or Codex

Two commands give the AI coding agent you already use a sealed sandbox to work in. The first adds kosa8's tools to the agent. The second teaches the agent when to use them.

$ kosa8 mcp install
Claude Desktop  registered in ~/Library/Application Support/Claude/claude_desktop_config.json
Cursor          registered in ~/.cursor/mcp.json
Claude Code     registered for every project (claude mcp add --scope user)

$ kosa8 skill install
claude-code  ~/.claude/skills/kosa8/SKILL.md
codex        ~/.codex/skills/kosa8/SKILL.md

Restart the client, then ask it something like "clone this repo into a kosa8 sandbox and run its tests".

In plain words

An AI agent that runs code on your computer can do anything you can: delete files, read your SSH keys, or send your API keys to someone else. With kosa8 connected, the agent gets its own small, sealed machine for that work. It can install packages, build, run tests and start web servers in there, and your files and network stay out of reach unless you allow them.

The tools (kosa8 mcp install) are what the agent can do: create a sandbox, run shell commands and code in it, read and write its files, use git, take checkpoints and rewind, and make a link to a web app running in it.
The skill (kosa8 skill install) is a short page of guidance the agent reads. It says when to reach for a sandbox (untrusted code, installs, builds, dev servers, anything risky) and how to use the tools well, including cleaning up afterwards.

kosa8 mcp install

With no arguments it sets up every client it finds. To choose, name them:

$ kosa8 mcp install cursor windsurf
$ kosa8 mcp install --print       # show what would be added, change nothing
$ kosa8 mcp install --uninstall   # take kosa8 out again

Client	Where it is registered
`claude-desktop`	`claude_desktop_config.json` in Claude's application-support folder
`claude-code`	Through Claude Code's own `claude mcp add --scope user`, so every project has it
`cursor`	`~/.cursor/mcp.json`
`windsurf`	`~/.codeium/windsurf/mcp_config.json`
`codex`	`~/.codex/config.toml`, as `[mcp_servers.kosa8]`

Each file keeps every other server and setting in it. The file as it was is saved next to it as .bak, and running the command again changes nothing. The entry starts kosa8 mcp serve, which talks to the kosa8 daemon on your machine, so start it first with kosa8 daemon start. The tools it exposes are listed in Tool servers (MCP), and every call goes through the same policy, approvals and audit log as the CLI.

kosa8 skill install

Agent	Where the skill goes
`claude-code`	`~/.claude/skills/kosa8/SKILL.md`, a personal skill for every project
`codex`	`~/.codex/skills/kosa8/SKILL.md`
`cursor`	`.cursor/rules/kosa8.mdc` in a project (`--project DIR`, default the current folder)

With no arguments it installs for Claude Code and Codex. A file at that path that kosa8 didn't write is left alone unless you pass --force. kosa8 skill show prints the skill, so you can read exactly what the agent is told or paste it into another agent's instructions.

What the agent does with it

Creates a sandbox with sandbox_create: no network unless the task needs it, set to stop itself after 30 idle minutes, and from your template if you have one (kosa8 template build).
Works in it with sandbox_shell (a shell that remembers cd and export), sandbox_code_run, the file tools and sandbox_git.
Takes a checkpoint before a risky step, and rewinds if it breaks something.
Shows you a web app with sandbox_preview, which gives a link that expires.
Deletes the sandbox when it's done.

You can watch along at any time with kosa8 sandbox ls, kosa8 audit and the Mac app.