# Connect your agent

Kestrel runs the agent you already use. It gives that agent a set of tools inside the sandbox and records every call they make.

Kestrel doesn't ship its own agent. It runs Claude Code, Codex, or your own loop inside the sandbox and hands it tools that work there: read and write files, run commands, search the repo and ask its memory. Each call is a step in the run's [trace](/runs/traces).

![The agent takes the task and calls one tool at a time. Each call goes out, the tool does its work, and the result comes back before the next step.](/illos/tool-calls.svg)

## Pick an agent

Set the agent in `kestrel.yaml`, or per run in the SDK.

```yaml kestrel.yaml
agent: claude-code
```

```ts TypeScript {4}
await kestrel.runs.create({
  repo: "acme/web-app",
  task: "Fix the flaky checkout test",
  agent: "codex",
});
```

| Agent | Value | Notes |
|---|---|---|
| Claude Code | `claude-code` | The default |
| Codex | `codex` | |
| Your own | `command` | Any process that speaks MCP over stdio |

## Bring your own loop

Point Kestrel at a command. It starts the process inside the sandbox and connects Kestrel's tools to it over MCP.

```yaml kestrel.yaml {2-4}
agent:
  command: node
  args: [agent/index.js]
  env: [OPENAI_API_KEY]
```

Secrets named under `env` come from **Settings → Secrets**, never from the repo.

## The tools

| Tool | What it does |
|---|---|
| `read_file` | Read a file from the repo |
| `write_file` | Write a file; the change joins the diff |
| `run_command` | Run a shell command and return its output |
| `search_repo` | Find code by text or by symbol |
| `recall` | Ask the repo's [memory](/agents/memory) |
| `remember` | Save a fact about the repo for later runs |

> [!TIP]
> Turn a tool off for one repo with `tools: { run_command: false }`. The agent then plans with what is left, and the trace shows any call it tried.