> ## Documentation Index
> Fetch the complete documentation index at: https://docs.boat.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Run a coding agent on your repo

> Step by step: connect GitHub and an AI key, clone your repository into a sandbox, and let Claude Code or Codex work on it.

You get a sandbox with your repository cloned in it, and an agent that works on it. It takes five steps.

## Before you start

* The `boat` CLI is installed and signed in. Read [Quickstart](/quickstart).
* Your account has GitHub connected. If you signed in with Google or an email code, open [Dashboard > Environment](https://boat.dev/dashboard?tab=environment) and click **Connect GitHub**.

## 1. Connect an AI key or subscription

Open [Agents & Proxying](https://boat.dev/dashboard?tab=agents). Sign in to Claude (Pro or Max) or ChatGPT, or paste an API key. Do this one time.

Without this step, the first prompt fails with `409 provider_not_configured`. For all options, read [Keys and subscriptions](/integrated-agents/keys).

## 2. Add the repository to your environment

```bash theme={null}
boat env add-repo base acme/web-app --branch main
```

`base` is your default environment. Every new sandbox on it clones `acme/web-app` into `/home/user/web-app`. Private repositories work.

## 3. Let the environment pass your GitHub access and AI keys

```bash theme={null}
boat env set base --safe-for-third-parties false --github true --agents-credentials true
```

* `--github true` lets the sandbox clone and push with your GitHub access.
* `--agents-credentials true` gives the agents the keys from step 1.
* **Safe for third parties** withholds all your secrets: variables, secret files, GitHub access and AI credentials. Turn it on only for sandboxes that other people use.

## 4. Start a sandbox

```bash theme={null}
boat new
```

The command prints the sandbox id, for example `bx_f7k2q9hd`. Check that the repository is there:

```bash theme={null}
boat exec bx_f7k2q9hd 'ls /home/user/web-app && git -C /home/user/web-app status'
```

The repository setup script, if you set one, runs at each start. Setup scripts are set on the dashboard only. Read [Setup scripts](/setup).

## 5. Give the agent a task

```bash theme={null}
boat prompt bx_f7k2q9hd --provider claude "Fix the failing tests, then commit on a new branch fix/tests and push it"
```

* The command prints what the agent does, and exits when the turn ends.
* Use `--provider codex` for Codex. Omit `--provider` to use your default harness.
* With one repository, the agent starts inside the repository folder.
* To send more work in the same thread, run `boat prompt bx_f7k2q9hd "…"` again. The agent keeps its memory.
* To change the task while it works, run `boat steer bx_f7k2q9hd "…"`. Read [Steer a running turn](/integrated-agents/steering).

## After the task

| You want | Command |
| - | - |
| Watch the work from another terminal | `boat events bx_f7k2q9hd --follow` |
| Look at the changes yourself | `boat ssh bx_f7k2q9hd` |
| More time than the 1-hour auto-stop | `boat extend bx_f7k2q9hd --hours 6`. A running prompt also moves the deadline by itself |
| Stop and keep the disk | `boat stop bx_f7k2q9hd`. `boat resume` brings back the files and the conversation |

## Next

* [Run many agents in parallel](/recipes/parallel-agents)
* [Customize the harness: rules, MCP, skills](/integrated-agents/customize)
* [Repositories](/environments/repositories)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.