# Coding agents

Give Claude Code and other agents a container to work in, instead of your Mac.

Coding agents are good at installing things, running builds and trying ideas. You don't always want that happening on your Mac. With Kuvo, an agent can make its own Linux container, copy your code in, and do its work there, using nothing but the `kuvo` command.

## Why the CLI works well for agents

- **Plain output.** No spinners, colors or tables that only make sense to a person. Errors go to standard error.
- **Real exit codes.** `kuvo exec` exits with the command's own code, so an agent knows whether its tests passed.
- **Nothing to set up.** Containers are named in plain words, the app starts itself when needed, and `kuvo --help` explains every command with examples.

## A typical session

```sh
# A clean Ubuntu container with limits
kuvo new bench --cpus 2 --memory 2g

# Install what's needed
kuvo exec bench "apt-get update && apt-get install -y build-essential python3"

# Copy the project in (git-ignored files are skipped)
kuvo cp ~/code/parser bench

# Run it, from the project folder
kuvo exec -w /workspace/parser bench "make test"

# Bring a result back
kuvo cp bench:/workspace/parser/report.json .

# Done for now: keep it for a while, or remove it
kuvo archive bench
```

## Telling your agent about Kuvo

Most agents read a project instructions file. Adding a few lines is usually enough:

```markdown
## Running code

Don't install packages or run untrusted code on this Mac. Use a Kuvo container:

- `kuvo new <name>` creates an Ubuntu container (see `kuvo new --help` for limits).
- `kuvo cp <path> <name>` copies code in; `kuvo exec <name> "<command>"` runs it.
- `kuvo archive <name>` when you're done.
```

For Claude Code, that file is `CLAUDE.md` in your project.

## Who created what

Containers made with `kuvo new` are labeled with who made them, and Kuvo shows it in `kuvo ls` and in the window's title bar.

- In a Claude Code session, the label is **Claude Code**, detected from the `CLAUDECODE` environment variable that Claude Code sets.
- Otherwise it's **you**.
- Set `KUVO_CREATOR` to use your own label, for example `KUVO_CREATOR="Release bot" kuvo new ci`.

The label is stored on the container as `run.kuvo.creator`, so you can filter by it with the docker command too:

```sh
docker ps -a --filter label=run.kuvo.creator="Claude Code"
```

## Keeping agents contained

A container is a good boundary for everyday work, not a security sandbox for hostile code. Some sensible defaults:

- Use `--no-network` when the work doesn't need the internet.
- Set `--cpus` and `--memory` so a runaway build can't slow down your Mac.
- Copy code in with `kuvo cp` instead of bind-mounting your folders, so changes stay in the container until you copy them back.
- Archive containers when a task is done. They're cleaned up automatically after the retention period.