This guide offers an overview of the OM1 agent runtime system, helping developers understand its core components and workflows.

Inside, you’ll find detailed explanations of OM1’s CLI commands, recommended project structure, step-by-step instructions for adding new actions, and guidance on configuring your agent for different environments. Additionally, the guide includes practical development tips to streamline your workflow, along with a reference to optional environment variables that can be used to customize the runtime behavior of your agents.

Whether you’re just getting started with OM1 or looking to optimize an existing project, this guide will equip you with the tools and best practices to develop, deploy, and maintain high-performance agents.

​
CLI

The OpenMind OS provides a command-line interface (CLI) to manage agents and projects.

The main entry point is src/run.py which provides the following commands:

  • start: Start an agent with a specified config
Start an agent with a specified config
python src/run.py start [config_name] [--debug]

  • config_name: Name of the config file (without .json5 extension) in the config directory

  • --debug: Optional flag to enable debug logging

​
Linting and Testing

Maintaining code quality and ensuring your agents work correctly is crucial when developing with OpenMind OS (OM1). This section covers recommended linting and testing practices to help you catch errors early, maintain code consistency, and validate agent behavior before deployment.

To check/format your code, run:

uv run ruff check . --fix && uv run black . && uv run isort .

To automatically run the lint check before committing, install pre-commit and execute pre-commit install. This ensures that pre-commit checks run before each commit. Additionally, you can manually trigger all checks by running pre-commit run --all-files.

​
Unit Testing

To unit test the system, run:

uv run pytest --log-cli-level=DEBUG -s

Use type hints and docstrings for better code maintainability.

​
Adding New Actions

Actions are the core capabilities of an agent. For example, for a robot, these capabilities are actions such as movement and speech. Each action consists of:

  1. Interface (interface.py): Defines input/output types.
  2. Implementation (implementation/): Business logic, if any. Otherwise, use passthrough.
  3. Connector (connector/): Code that connects OM1 to specific virtual or physical environments, typically through middleware (e.g. custom APIs, ROS2, Zenoh, or CycloneDDS)

Example action structure:

Example Action Structure
actions/

└── move_{unique_hardware_id}/

    ├── interface.py      # Defines MoveInput/Output

    ├── implementation/

    │   └── passthrough.py

    └── connector/

        ├── ros2.py       # Maps OM1 data/commands to hardware layers and robot middleware

        ├── zenoh.py

        └── unitree.py

In general, each robot will have specific capabilities, and therefore, each action will be hardware specific. For example, if you are adding support for the Unitree G1 Humanoid version 13.2b, which supports a new movement subtype such as dance_2, you could name the updated action move_unitree_g1_13_2b and select that action in your unitree_g1.json configuration file.

Was this page helpful?