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

# Run Codex on a repository

> Prepare files and credentials to run Codex on a repository, then inspect the runner's results.

Run Codex on a repository in a machine with your project dependencies. You control the files, credentials, and working directory.

## Before you start

Install and authenticate the [CLI](https://docs.bead.run/installation.md), choose a published [coding template](https://docs.bead.run/templates/overview.md), and prepare an [AI credential profile](https://docs.bead.run/agents/credentials.md).

## Create a machine

```bash theme={null}
bead create --template agents --size small --kind temporary --timeout 900
```

Replace `ID` below with the returned machine ID.

## Prepare your repository

Clone a public repository into an explicit directory:

```bash theme={null}
bead exec ID 'git clone https://github.com/octocat/Hello-World.git /root/project'
bead exec ID 'git status --short' --cwd /root/project
```

For local files, use [file transfer](https://docs.bead.run/connect/files.md). For private repositories, supply your own repository credentials through authenticated guest access. An AI profile does not establish repository access.

## Give the agent a task

Replace `PROFILE_UUID` with your saved profile UUID. Retain a request UUID before dispatch so you can reuse it if the response is lost.

```bash theme={null}
bead prompt ID 'Read the repository and explain how it works' \
  --cwd /root/project --profile PROFILE_UUID \
  --request-id 72d04cb0-305e-49d0-8d88-d92a9b381fd3
bead events ID --follow
```

The working directory must already exist. The default is `/root`; `/workspace` is not created automatically.

## Inspect the result

```bash theme={null}
bead status ID
bead diff ID --cwd /root/project
bead get ID /root/project/README --output ./README.remote
```

Read the runner's terminal events and review the changes. Download the files you need before `bead delete ID`. See [steering and approvals](https://docs.bead.run/agents/control.md) and [parallel work](https://docs.bead.run/use-cases/parallel-work.md).


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