Structure & Configuration

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.

repository/
├── rollouts/                            # AgentWorkflow + Grader code
├── configs/
│   ├── eval/                            # Evaluation configs
│   ├── AGENTS.md                        # AI assistant instructions for configs
│   ├── training/
│   │   └── default.toml                 # Training config template
│   └── benchmark/                       # Optional: benchmark submit configs
│       └── default.toml                 # Benchmark config template
├── data/                                # Local test datasets
├── pyproject.toml                       # Python project config
├── README.md                            # Project readme
├── AGENTS.md                            # Canonical AI coding assistant instructions
├── CLAUDE.md                            # Claude Code pointer to AGENTS.md
└── .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`

configs/benchmark/ is optional and used only by osmosis benchmark submit; osmosis doctor and osmosis doctor --fix do not require or create it. Run a health check from anywhere inside the workspace directory:

osmosis doctor

Repair missing scaffold directories without overwriting existing files:

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.

rollouts/
└── my-rollout/
    ├── main.py          # Entrypoint: defines AgentWorkflow + Grader
    ├── pyproject.toml   # Rollout package dependencies
    └── README.md        # Rollout notes

Create a new rollout scaffold:

osmosis rollout init <name>

Or apply a starter template:

osmosis template list
osmosis template apply multiply-local-strands

`configs/`

Configuration files for evaluation and training, plus optional benchmark submission configs.

Subdirectory	Required by `doctor`	Purpose	Reference
`configs/training/`	Yes	Training run configs for `osmosis train submit`	Training Config
`configs/eval/`	Yes	Evaluation run configs for `osmosis eval submit`	Evaluation Config
`configs/benchmark/`	No	Optional benchmark run configs used only by `osmosis benchmark submit`	Benchmark Config

The default templates and rollout-specific evaluation and training configs are pre-populated with required fields and commented-out optional settings. See Configuration 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 and evaluation configs.

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.

pyproject.toml

[project]
name = "osmosis-workspace"
description = "Osmosis workspace repository"
version = "0.1.0"
requires-python = ">=3.12"
dependencies = [
    "osmosis-ai[server,strands]>=0.3.0,<0.4",
]

`AGENTS.md` & `CLAUDE.md`

AGENTS.md is the canonical instruction file for AI coding assistants. CLAUDE.md points Claude Code to AGENTS.md; it is not a second, independently maintained set of instructions. The nested configs/AGENTS.md adds config-specific rules for files under configs/.

Generated Runtime State

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

Get started

Runs

Workspace

Reference

Required Directories

`rollouts/`

`configs/`

`data/`

`pyproject.toml`

`AGENTS.md` & `CLAUDE.md`

Generated Runtime State

Next Steps

Workspace Repository

Configuration Files

​Required Directories

​rollouts/

​configs/

​data/

​pyproject.toml

​AGENTS.md & CLAUDE.md

​Generated Runtime State

​Next Steps

Workspace Repository

Configuration Files

Required Directories

`rollouts/`

`configs/`

`data/`

`pyproject.toml`

`AGENTS.md` & `CLAUDE.md`

Generated Runtime State

Next Steps