Quick Start - Osmosis

Clone the official template repository, implement your agent logic, and connect to the Osmosis training cluster — the fastest path to a working Remote Rollout server.

Create Your Project from the Template

Create Repository

Visit our official template repository:

osmosis-remote-rollout-example

Click the “Use this template” button in the top-right corner to create your own repository based on this template.

This template includes a complete project structure, example code, and test data so you can start developing immediately.

Clone and Install Dependencies

Clone your newly created repository and install dependencies:

uv sync

If you don’t have uv installed, you can also use pip:

pip install osmosis-ai[server]

Authenticate with the Osmosis Platform to enable server registration:

uv run osmosis login

This will open your browser for authentication. After logging in, your credentials are saved to ~/.config/osmosis/credentials.json.You can verify your login status with:

uv run osmosis whoami

The server uses your credentials to register with Osmosis Platform, enabling the training system to discover and connect to your server.

Run the Server

Start the server using the SDK CLI:

uv run osmosis serve -m server:agent_loop

You should see output similar to:

INFO:     Osmosis RolloutServer starting...
INFO:     Agent: calculator
INFO:     Tools: 4
INFO:     Uvicorn running on http://0.0.0.0:9000

Template Structure

The template repository contains the following key components:

my-rollout-server/
├── server.py           # Agent Loop main file
├── tools.py            # Tool definitions and execution logic
├── rewards.py          # Reward computation (optional)
├── test_data.jsonl     # Test dataset
├── pyproject.toml      # Project dependencies
└── README.md           # Documentation

Core Concept: Agent Loop

The Agent Loop is the core of Remote Rollout. It inherits from RolloutAgentLoop and implements two required methods:

from osmosis_ai.rollout import RolloutAgentLoop, RolloutContext, RolloutResult, RolloutRequest, create_app

class CalculatorAgent(RolloutAgentLoop):
    name = "calculator"

    def get_tools(self, request: RolloutRequest):
        """Return available tools."""
        return CALCULATOR_TOOLS  # Defined in tools.py

    async def run(self, ctx: RolloutContext) -> RolloutResult:
        """Execute the agent loop."""
        ...  # See template repo for full implementation

agent_loop = CalculatorAgent()
app = create_app(agent_loop)

See the Agent Loop Guide for a complete implementation reference with tool execution, reward computation, and advanced patterns.

Tool Definitions

Tools are defined using the OpenAI function calling format:

CALCULATOR_TOOLS = [
    {
        "type": "function",
        "function": {
            "name": "multiply",
            "description": "Multiply two numbers",
            "parameters": {
                "type": "object",
                "properties": {
                    "a": {"type": "number", "description": "First number"},
                    "b": {"type": "number", "description": "Second number"}
                },
                "required": ["a", "b"]
            }
        }
    }
]

Validation and Testing

Validate Agent Configuration

Before running, validate your agent implementation using the CLI:

uv run osmosis validate -m server:agent_loop

Expected output:

✓ Agent loop validated successfully
  Name: calculator
  Tools: 4 (add, subtract, multiply, divide)

Local Testing

The template includes a test_data.jsonl test dataset. Set your API key and run tests:

export OPENAI_API_KEY="your-key-here"

# Run batch tests
uv run osmosis test -m server:agent_loop -d test_data.jsonl

# Limit number of tests
uv run osmosis test -m server:agent_loop -d test_data.jsonl --limit 10

# Use a different model
uv run osmosis test -m server:agent_loop -d test_data.jsonl --model anthropic/claude-sonnet-4-5

For step-by-step debugging and advanced testing options, see Test Mode.

Development Tips

Enable Hot Reload

Enable auto-reload during development to automatically restart the server when code changes:

uv run osmosis serve -m server:agent_loop --reload

Enable Debug Logging

Write execution traces to files for debugging:

uv run osmosis serve -m server:agent_loop --log ./logs

Log file structure:

logs/
└── {timestamp}/
    ├── rollout-abc123.jsonl
    └── rollout-def456.jsonl

Skip login and platform registration for local development:

uv run osmosis serve -m server:agent_loop --local

Local mode disables API key authentication and platform registration. This is intended for development only and should not be used in production.

Remote Rollout

​Create Your Project from the Template

osmosis-remote-rollout-example

​Template Structure

​Core Concept: Agent Loop

​Tool Definitions

​Validation and Testing

​Validate Agent Configuration

​Local Testing

​Development Tips

​Enable Hot Reload

​Enable Debug Logging

​Local Mode (No Login Required)

​Next Steps

Agent Loop Guide

Test Mode

Create Your Project from the Template

Template Structure

Core Concept: Agent Loop

Tool Definitions

Validation and Testing

Validate Agent Configuration

Local Testing

Development Tips

Enable Hot Reload

Enable Debug Logging

Local Mode (No Login Required)

Next Steps