# How to Export Agent Trajectories for Training Reinforcement Learning Models in Cua

> Export Cua agent trajectories for RL training using the CLI or zip_trajectory() function. Streamline your reinforcement learning pipelines with this essential data format. Learn how now.

- Repository: [Cua/cua](https://github.com/trycua/cua)
- Tags: how-to-guide
- Published: 2026-04-27

---

**You can export agent trajectories from Cua using the `cua trajectory view` CLI command to generate a zip file, or programmatically via the `zip_trajectory()` function in [`cua_cli/utils/trajectory_recorder.py`](https://github.com/trycua/cua/blob/main/cua_cli/utils/trajectory_recorder.py), which packages screenshots and JSON responses into a format ready for RL training pipelines.**

The `trycua/cua` framework automatically records every agent interaction as a trajectory during `cua do` executions. To export agent trajectories for training reinforcement learning models, you can leverage built-in CLI utilities or Python APIs that package the recorded session data—screenshots, tool calls, and timestamps—into standardized zip archives.

## Where Trajectories Are Recorded

Every `cua do` interaction is recorded as a sequence of turn folders under **`~/.cua/trajectories/<machine>/<timestamp>/`**. The recording logic in [`cua_cli/utils/trajectory_recorder.py`](https://github.com/trycua/cua/blob/main/cua_cli/utils/trajectory_recorder.py) handles session creation, while `_maybe_record_turn` in [`cua_cli/commands/do.py`](https://github.com/trycua/cua/blob/main/cua_cli/commands/do.py) triggers the capture after each turn.

The directory structure follows this pattern:

```

~/.cua/trajectories/
  └─ <machine_name>/
       └─ 20241015-143210/
            ├─ turn_001/
            │    ├─ screenshot.png
            │    └─ turn_001_agent_response.json
            ├─ turn_002/
            │    ├─ screenshot.png
            │    └─ turn_002_agent_response.json
            └─ ...

```

Each `turn_###_agent_response.json` follows the **TrajectoryViewer** schema and contains the model name, timestamps, and the exact `computer_call` action the agent performed.

## Export Methods

You have three primary options to export recorded trajectories: the CLI convenience command, manual session selection, or direct Python API access.

### Using the CLI (`cua trajectory view`)

The `cua trajectory view` command is the fastest way to export agent trajectories. It automatically zips the session and launches a local CORS file server for immediate download.

```bash

# Export the most recent session (default)

cua trajectory view

# Export a specific session by machine and timestamp

cua trajectory view my-container 20241015-143210

```

The command outputs a zip file path and a local viewer URL. The zip file (e.g., `20241015-143210.zip`) is created beside the session folder under `~/.cua/trajectories/`. You can copy this file directly to your training infrastructure:

```bash
cp ~/.cua/trajectories/my-container/20241015-143210.zip /my/rl/data/

```

Stop the local server when finished with `cua trajectory stop`.

### Using the Python API

For embedding export logic in training scripts or CI pipelines, import the recorder utilities directly from [`cua_cli/utils/trajectory_recorder.py`](https://github.com/trycua/cua/blob/main/cua_cli/utils/trajectory_recorder.py).

```python
from pathlib import Path
from cua_cli.utils.trajectory_recorder import list_trajectories, zip_trajectory

# List all sessions for a specific machine

sessions = list_trajectories(machine="my-container")
latest = sessions[-1]  # Most recent entry

session_path = Path(latest["path"])

# Create the zip archive (returns Path to the .zip file)

zip_path = zip_trajectory(session_path)
print(f"Trajectory ready at: {zip_path}")

```

The `zip_trajectory()` function creates a TrajectoryViewer-compatible archive next to the source directory, preserving the original turn structure.

## Using Exported Data for RL Training

The exported zip contains precisely the data you need for reinforcement learning training loops:

- **State**: Load `turn_###/screenshot.png` to obtain the visual observation at each timestep.
- **Action**: Parse `turn_###_agent_response.json`; the JSON contains the tool call `type` and parameters representing the agent's action.
- **Reward**: Derive from outcome metrics, success flags in the response, or custom heuristics computed from the screenshot sequence.

Because the archive maintains the original `turn_*/` directory structure, you can unzip and iterate over folders chronologically in your data loader.

## Practical Code Examples

### Recording Trajectories

Recording is enabled by default for every `cua do` execution via the `_maybe_record_turn` helper in [`cua_cli/commands/do.py`](https://github.com/trycua/cua/blob/main/cua_cli/commands/do.py).

```bash

# Standard execution records automatically

cua do my-agent "open notepad"

# Disable recording for a specific run

cua do --no-record my-agent "quick task"

```

### Listing and Managing Sessions

The [`cua_cli/commands/trajectory.py`](https://github.com/trycua/cua/blob/main/cua_cli/commands/trajectory.py) module provides utilities to manage stored data.

```bash

# Display all sessions in a human-readable table

cua trajectory ls

# Remove sessions older than 30 days

cua trajectory clean --machine my-container --older-than 30 -y

```

These commands invoke `list_trajectories()` and `clean_trajectories()` from the recorder module.

### Programmatic Export in Training Scripts

Embed trajectory export directly into your RL pipeline:

```python
from pathlib import Path
from cua_cli.utils.trajectory_recorder import list_trajectories, zip_trajectory

def export_latest(machine: str) -> Path:
    sessions = list_trajectories(machine=machine)
    if not sessions:
        raise RuntimeError(f"No trajectories found for {machine}")
    latest_path = Path(sessions[-1]["path"])
    return zip_trajectory(latest_path)

# Integration example

zip_file = export_latest("my-container")

# Pass zip_file to torch.utils.data.Dataset or custom loader

```

## Key Source Files

| File | Role |
|------|------|
| [`cua_cli/utils/trajectory_recorder.py`](https://github.com/trycua/cua/blob/main/cua_cli/utils/trajectory_recorder.py) | Core recorder containing `ensure_session`, `record_turn`, `zip_trajectory`, and `list_trajectories` |
| [`cua_cli/commands/do.py`](https://github.com/trycua/cua/blob/main/cua_cli/commands/do.py) | Command implementation with `_maybe_record_turn` logic and `--no-record` flag handling |
| [`cua_cli/commands/trajectory.py`](https://github.com/trycua/cua/blob/main/cua_cli/commands/trajectory.py) | CLI frontend for `ls`, `view`, `clean`, and `stop` subcommands |

## Summary

- Trajectories are stored under **`~/.cua/trajectories/<machine>/<timestamp>/`** with screenshots and JSON responses for each turn.
- Use **`cua trajectory view`** to quickly zip and serve the latest session, or specify a machine and timestamp for targeted exports.
- Import **`zip_trajectory`** and **`list_trajectories`** from [`cua_cli/utils/trajectory_recorder.py`](https://github.com/trycua/cua/blob/main/cua_cli/utils/trajectory_recorder.py) for programmatic access in Python training scripts.
- Each turn folder contains `screenshot.png` (state) and `turn_###_agent_response.json` (action data) compatible with standard RL training formats.
- Recording is enabled by default during `cua do` executions and can be disabled per-run with the **`--no-record`** flag.

## Frequently Asked Questions

### Where are trajectory files stored on disk?

Trajectory files are stored in **`~/.cua/trajectories/<machine_name>/<timestamp>/`**, where each session folder contains sequentially numbered turn subdirectories with screenshots and JSON response files.

### Can I disable trajectory recording for specific runs?

Yes. Pass the **`--no-record`** flag to any `cua do` command. The `_maybe_record_turn` function in [`cua_cli/commands/do.py`](https://github.com/trycua/cua/blob/main/cua_cli/commands/do.py) checks this flag before invoking the recorder.

### What data format is used for RL training?

Each turn provides a `screenshot.png` (visual state) and a `turn_###_agent_response.json` containing the agent's tool call action, model metadata, and timestamps. The TrajectoryViewer schema ensures consistent formatting for parsing state-action pairs.

### How do I export trajectories programmatically in Python?

Import `list_trajectories` and `zip_trajectory` from [`cua_cli/utils/trajectory_recorder.py`](https://github.com/trycua/cua/blob/main/cua_cli/utils/trajectory_recorder.py). Use `list_trajectories(machine="name")` to locate sessions, then pass the session path to `zip_trajectory()` to generate the archive file.