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

# Structure & Configuration

> Understand the workspace repository layout and configuration files

A workspace directory is a local clone of the GitHub workspace repository connected to your platform workspace. The platform creates new workspace repositories from the Osmosis workspace template.

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
repository/
├── rollouts/                            # AgentWorkflow + Grader code
├── configs/
│   ├── eval/                            # Evaluation configs
│   ├── AGENTS.md                        # AI assistant instructions for configs
│   └── training/
│       └── default.toml                 # Training config template
├── data/                                # Local test datasets
├── pyproject.toml                       # Python project config
├── README.md                            # Project readme
├── AGENTS.md                            # AI coding assistant instructions
├── CLAUDE.md                            # Claude Code instructions
└── .gitignore                           # Git ignore rules
```

***

## Required Directories

The CLI expects these directories to exist:

| Path                | Purpose                                             |
| ------------------- | --------------------------------------------------- |
| `rollouts/`         | Rollout code, one subdirectory per rollout          |
| `configs/training/` | Training run TOML files for `osmosis train submit`  |
| `configs/eval/`     | Evaluation run TOML files for `osmosis eval submit` |
| `data/`             | Local datasets used by `osmosis dataset upload`     |

Run a health check from anywhere inside the workspace directory:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
osmosis doctor
```

Repair missing scaffold directories without overwriting existing files:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
osmosis doctor --fix
```

## `rollouts/`

The directory where your AgentWorkflow and Grader code lives. Each rollout is a subdirectory containing an entrypoint file (typically `main.py`) that defines the agent workflow and grading logic.

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
rollouts/
└── my-rollout/
    ├── main.py          # Entrypoint: defines AgentWorkflow + Grader
    ├── pyproject.toml   # Rollout package dependencies
    └── README.md        # Rollout notes
```

Create a new rollout scaffold:

```cli theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
osmosis rollout init <name>
```

Or apply a starter template:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
osmosis template list
osmosis template apply multiply-local-strands
```

## `configs/`

Configuration files for the two CLI operations: training and evaluation.

| Subdirectory        | Purpose                                          | Reference                                            |
| ------------------- | ------------------------------------------------ | ---------------------------------------------------- |
| `configs/training/` | Training run configs for `osmosis train submit`  | [Training Config](/cli/config-files#training-config) |
| `configs/eval/`     | Evaluation run configs for `osmosis eval submit` | [Evaluation Config](/cli/config-files#eval-config)   |

The `configs/training/default.toml` template and rollout-specific evaluation configs named `configs/eval/<rollout-name>.toml` are pre-populated with required fields and commented-out optional settings. See [Configuration Files](/cli/config-files) for the full TOML schema reference.

## `data/`

Directory for local dataset files. Upload them to the platform with `osmosis dataset upload`, then reference the uploaded dataset by name from your [training](/cli/config-files#training-config) and [evaluation](/cli/config-files#eval-config) configs.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
osmosis dataset upload data/<dataset-file>.jsonl
```

## `pyproject.toml`

Standard Python project configuration for the workspace repository. Individual rollouts can also have their own `rollouts/<name>/pyproject.toml` files for rollout-specific dependencies.

```toml pyproject.toml theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
[project]
name = "osmosis-workspace"
description = "Osmosis workspace repository"
version = "0.1.0"
requires-python = ">=3.12"
dependencies = [
    "osmosis-ai>=0.2.21",
]
```

## `AGENTS.md` & `CLAUDE.md`

Instruction files for AI coding assistants. `AGENTS.md` provides general guidance for any AI assistant (GitHub Copilot, Cursor, etc.), while `CLAUDE.md` contains Claude Code-specific instructions.

Both files describe the workspace structure, conventions, and Osmosis-specific patterns so your AI assistant can effectively help you write rollout code.

## Generated Runtime State

The CLI may create local runtime files under `.osmosis/`, such as exported metrics. Treat those as local state, not source code.

## Next Steps

<CardGroup cols={2}>
  <Card title="Workspace Repository" icon="code-branch" href="/cli/workspace/repository">
    Learn how the CLI resolves the connected workspace.
  </Card>

  <Card title="Configuration Files" icon="file-lines" href="/cli/config-files">
    Review training and evaluation TOML schemas.
  </Card>
</CardGroup>