Skip to main content
roz is configured through a combination of a local config file (roz.toml), a project-level agent instructions file (AGENTS.md), and environment variables.

​
roz.toml

The primary configuration file. Created by roz setup and stored in your project root. 
[agent]
model = "claude-sonnet-4-20250514"
provider = "anthropic"            # anthropic, openai, google, ollama
max_context_tokens = 200000

[spatial]
enabled = true
safety_filter = true
control_rate_hz = 100

[sim]
default_robot = "ur5"
auto_start = true                 # Start sim container on `roz` launch

[server]
api_url = "http://localhost:8080"

​
Agent Section

KeyTypeDefaultDescription
modelstring"claude-sonnet-4-20250514"LLM model to use.
providerstring"anthropic"LLM provider: anthropic, openai, google, ollama.
max_context_tokensinteger200000Context window budget. The agent warns when usage exceeds 30%.

​
Spatial Section

KeyTypeDefaultDescription
enabledbooltrueEnable spatial (OODA) mode for physical robot control.
safety_filterbooltrueEnable the safety filter that clamps all channel values.
control_rate_hzinteger100WASM controller execution frequency.

​
Sim Section

KeyTypeDefaultDescription
default_robotstring"ur5"Robot type for roz sim start when no argument is given.
auto_startbooltrueAutomatically start the sim container when launching roz.

​
Server Section

KeyTypeDefaultDescription
api_urlstring"http://localhost:8080"API endpoint for cloud sessions.

​
AGENTS.md

A Markdown file in your project root that provides project-specific instructions to the agent. The agent reads this file at session start and includes it as a system context block. 
# AGENTS.md

## Project Context
This workspace controls a UR5 arm mounted on a table.
The home position is [0, -1.57, 0, -1.57, 0, 0] radians.

## Safety Rules
- Never move joint velocities above 1.0 rad/s during calibration.
- Always return to home position before stopping.

## Preferred Behaviors
- Use smooth sinusoidal trajectories for demonstrations.
- Log joint positions after every move_to_pose call.
The agent’s constitution has four tiers. AGENTS.md can refine Tier 3 (Operational) rules and override Tier 4 (Quality) defaults, but it cannot override Tier 1 (Safety-Critical) or Tier 2 (Security) rules.

​
Environment Variables

VariableRequiredDescription
ANTHROPIC_API_KEYFor Anthropic providerAPI key for Claude models.
OPENAI_API_KEYFor OpenAI providerAPI key for GPT models.
GOOGLE_API_KEYFor Google providerAPI key for Gemini models.
OLLAMA_URLFor Ollama providerOllama server URL (default: http://localhost:11434).
ROZ_API_URLFor cloud sessionsAPI server endpoint.
DATABASE_URLFor roz-serverPostgreSQL connection string.
NATS_URLFor roz-server/workerNATS server URL.
Environment variables override values in roz.toml. You can also set them in a .env file in the project root.

​
LLM Provider Configuration

​
Anthropic (default)

export ANTHROPIC_API_KEY="sk-ant-..."

[agent]
provider = "anthropic"
model = "claude-sonnet-4-20250514"
Supported models: Claude 4, Claude 3.5 Sonnet, and other Anthropic models.

​
OpenAI

export OPENAI_API_KEY="sk-..."

[agent]
provider = "openai"
model = "gpt-4o"
Supported models: GPT-4, GPT-4o, and other OpenAI chat models.

​
Google

export GOOGLE_API_KEY="AI..."

[agent]
provider = "google"
model = "gemini-2.5-pro"
Supported models: Gemini 2.5 Pro, Gemini 2.5 Flash, and other Gemini models.

​
Ollama (local)

No API key needed. Start the Ollama server first: 
ollama serve
ollama pull llama3

[agent]
provider = "ollama"
model = "llama3"
Ollama runs models locally with no network dependency. Useful for development, air-gapped environments, or when you want full control over the model.

​
API Authentication

For cloud deployments (roz-server), API keys use the scheme roz_sk_<random>. Pass the key as a Bearer token: 
curl -H "Authorization: Bearer roz_sk_..." http://localhost:8080/api/v1/sessions
Keys do not expire by default. They are permanent until explicitly revoked.

​
Source Code

Configuration handling: crates/roz-cli/src/commands/config.rs