Skip to main content

​
What is an Environment?

An environment is a long-running server that implements the Open Reward Standard (ORS) protocol for agent environments. When an environment is created, a workspace will be provisioned, giving you storage and isolation. What environments provide:
  • Tools: Functions that agents can call to interact with the environment
  • Tasks: Specific problems or challenges for agents to solve
  • Prompts: Instructions given to agents for each task
  • Rewards: Feedback signals indicating task progress or completion
  • Sessions: Stateful, durable connections with agents
  • Automatic scaling: Environments scale up and down based on demand

​
Environment Lifecycle

​
1. Creation

Create environments through the OpenReward Web UI: 
1. In header header, click the + button
   ↓
2. Click "New environment"
   ↓
3. Enter name and description
   ↓
4. Set visibility (public/private)
   ↓
5. Environment created with workspace

​
2. Deployment

Once you have created your environment, you can deploy your ORS server code to it: See Local Development for more details on how to develop your environment server locally. Option A - GitHub (Recommended): 
1. Connect GitHub repository to environment
   ↓
2. Push code to repository
   ↓
3. OpenReward automatically builds and deploys
   ↓
4. Environment server starts accepting sessions
See GitHub Integration for setup. Option B - Direct Upload: Upload a container image directly to your environment (coming soon).

​
3. Running

Once deployed, agents can connect to your environment: Agent interaction: 
from openreward import OpenReward

client = OpenReward(api_key="your-api-key")

# Get environment
environment = client.environments.get(name="username/my-environment")

# List available tasks
tasks = await environment.list_tasks(split="train")

# Create session
async with environment.session(task=tasks[0]) as session:
    # Get task prompt
    prompt = await session.get_prompt()

    # Call tools
    result = await session.call_tool("bash", {"command": "ls"})

    # Environment returns results directly
    print(result)

​
4. Automatic Scaling

Environments automatically scale based on concurrent sessions. Autoscaling settings are configurable when making the environment and can be changed in the environment settings page. Benefits:
  • Pay only for active usage
  • No manual scaling needed
  • Always ready when agents connect

​
5. Updates

Pushing to the connected GitHub repository will automatically build and deploy a new version of the environment. Via GitHub (automatic): 
1. Push new code to GitHub
   ↓
2. OpenReward detects changes
   ↓
3. Builds new version
   ↓
4. Deploys the new version of the environment server

​
Sessions

​
What is a Session?

A session is a durable, stateful connection between an agent and your environment:
  • Unique: Each session has a unique ID, this is internally used to make sure you’re connecting to the correct environment server.
  • Stateful: Environment can maintain state between tool calls
  • Time-limited: Sessions expire after inactivity or when the session is deleted.
  • Sticky: Session stays connected to the same server instance

​
Using Sessions

Python SDK: 
# Create session with context manager (automatic cleanup)
with environment.session(task=task) as session:
    # Get initial prompt
    prompt = session.get_prompt()

    # Call tools multiple times
    result1 = session.call_tool("read_file", {"path": "README.md"})
    result2 = session.call_tool("bash", {"command": "python test.py"})

    # Session automatically cleaned up on exit
Session lifecycle: 
1. Agent creates session → Connected to environment
2. Agent calls tools → Results returned directly
3. Agent finishes task → Session ends
4. Context manager exits → Session automatically cleaned up

​
Tool Calling

Environments provide tools that agents can call: Example tool call: 
result = session.call_tool(
    tool_name="bash",
    arguments={"command": "ls -la"}
)

# Result returned directly from environment
print(result.output)       # Command output
print(result.finished)     # Task completion status
print(result.reward)       # Performance feedback
Tool results structure:
  • output: The tool’s return value
  • finished: Whether the task is complete
  • reward: Numeric feedback signal
  • error: Error message if tool call failed

​
Storage

​
Cloud Storage Integration

Each environment includes cloud storage accessible at /orwd_data/: Usage in environment server: 
from pathlib import Path

# Storage mounted at /orwd_data/
storage = Path("/orwd_data")

# Read dataset
with open(storage / "datasets" / "train.csv") as f:
    data = f.read()

# Write results
with open(storage / "results" / "metrics.json", "w") as f:
    json.dump(metrics, f)
Shared with sandboxes: Data in /orwd_data/ is accessible to both your environment server and any sandboxes you create. See Storage & Buckets for detailed configuration.

​
Next Steps

Your First Environment

Build and deploy your first environment

Sandboxes

Add isolated code execution to your environment

GitHub Deployment

Set up automatic deployments from GitHub

Storage & Buckets

Configure persistent storage for your environment