Quickstart Guide
To contribute to OopsieData, collect real-world robot policy rollouts (e.g. policy evaluation, play data collection, online RL training) with both successes and failures and use our toolkit to format them into a consistent storage format. Each episode should be annotated with a success label, and can optionally be annotated with a brief failure description with our annotation tool. Finally, upload your data to the project repository.
This page provides a brief overview of all the necessary steps to contribute to the project using our tooling:
For each step, we provide a quick overview below; more detailed instructions and code examples are provided in the Oopsie Toolkit section of this website. If you run into any issues, please reference it for any additional information and check the FAQ as well. If you still have questions, do not hesitate to open an issue on github or contact the team.
For people using coding agents, we have created a skill to help you quickly set up and integrate our toolkit. See setting up a coding agent below.
1. Registration
To submit data to the official Oopsie Data Project, you need to register your lab. We will review the registration and send you the lab-specific ID and huggingface token which are used to submit data to the central repository. Only your lab will have access to this data until the public release, and we will notify all contributors before their data gets released!
To register, please use the registration form. We only need one registration per lab. If your lab is already registered, please contact your lab contact to get the submission token.
2. Installation and setup
2.1 Installation
To install our data collection and annotation tooling, we recommend using uv or pip. We tested our toolkit with python versions 3.8 and 3.12, please contact us if you run into trouble with another version.
The package is on PyPI, so to install oopsie-data-tools, simply activate your environment and run
pip install oopsie-data-tools
# or, in a uv project: uv add oopsie-data-tools
This will give you a CLI tool called oopsie-data that you can call to setup, collect, annotate, and submit your data.
2.1.5 Setting up a coding agent (optional)
Nothing in the toolkit actually requires access to a coding agent. But if you drive the toolkit through a coding agent such as Claude Code, Cursor CLI, or Codex, the package ships a shared skill called “oopsie-data” that can help with integration and setup. You can install the skill by running:
oopsie-data install-skill --agent claude # installs under .claude/skills/ for Claude Code
oopsie-data install-skill --agent [cursor|codex] # installs under .agents/skills/ for Cursor and Codex
oopsie-data install-skill --agent agents # installs under .agents/skills/ for any agent following the shared convention
oopsie-data install-skill --agent none # installs under ./skills/ for copying onward yourself
This installs the same skill for the specified agent in the current project. To make the skill available to all agents in every project, install it under your home directory:
oopsie-data install-skill --agent [claude|cursor|codex|agents] --user # installs into your home directory for all agents
To update the skill to the latest version, run:
oopsie-data install-skill --check # check whether installed skills are stale
oopsie-data install-skill --agent [claude|cursor|codex|agents] --force # replaces the project-level skill
2.2 Setting up the contributor config
Run oopsie-data init. It prompts for the lab id and huggingface token you received after registration, checks the token, and writes the file where the other commands will find it.
To do it by hand instead, put those values in contributor_config.yaml. If you cloned the repository, that file lives in configs/; if you installed the package without a clone, create it at ~/.config/oopsie-data/contributor_config.yaml (see where credentials live). Please make sure that you use the exact provided lab id (including capitalization) otherwise you cannot access the lab-specific repository.
lab_id: <EXACT_LAB_ID>
huggingface_token: <HF_TOKEN>
2.3 Creating a robot profile
Oopsie-data is a cross-embodiment dataset, and we use a robot profile to detail the specific robot and controller setup used from each contribution. The robot profile also captures the policy used for the rollout, since some keys, such as the action space, can be different for different policies on the same robot embodiment. This means you should overwrite the policy field or create a separate profile for policies with different action spaces.
A template and example robot profiles can be generated by running oopsie-data new-profile or found in config/robot_profiles. Keep your own profile next to your robot code and load it by path. Start by modifying the template (or the closest existing profile) to reflect your robot and controller setup. For details on the robot profile format, please refer to the full instructions.
3. Data recording and annotation
3.1 Data collection
If you are using a standard framework for policy execution and evaluation, check the examples provided in examples/inference_examples for a growing list of ready-to-use scripts.
Oopsie-tools supports three workflows for data collection and annotation:
- In-the-loop collection and annotation: As the policy rollout each episode on the robot, collect the data and annotate as each episode finishes. For a minimal code example, see option 1 here.
- Bulk collection and annotation: Use the tool to record many rollout episodes data at once, then annotate the data in a separate step after all rollout data is collected. For a minimal code example, see option 2 here.
- Custom collection and bulk annotation: If your setup is incompatible with our EpisodeRecorder, or if you have already collected data and simply want to format it into the Oopsie Data format for annotation and submission, see option 3 here.
3.2 Annotation
We provide a web-based annotation tool that allows you to quickly annotate your data with information about the suboptimalities or failures that occurred during the rollout.
To launch the tool in your browser after collecting data, simply run
oopsie-data annotate --samples-dir <DIR> --port <PORT> --annotator-name <YOUR_NAME>
The samples_dir should be the top level directory where your samples were recorded, the port specifies on which port the webserver can be accessed (navigate to localhost:<port> to see the web interface) and annotator_name records who provided the annotation.
4. Data submission
To submit your data, you need to ensure that you have provided the lab_id and huggingface token, and that your data is properly annotated. After doing this, you can simply run
oopsie-data upload --path /path/to/formatted_data