← Back to docs

Prerequisites

  • Python 3.13+
  • uv package manager
  • An OpenAI-compatible API key (set OPENAI_API_KEY)

Install

git clone https://github.com/smith-nathanh/rho-agent.git
cd rho-agent
uv sync

Start an interactive session

export OPENAI_API_KEY=sk-...
uv run rho-agent main

This starts a REPL with the default readonly profile. The agent can inspect files and run read-only shell commands, but cannot modify anything.

Start a development session

uv run rho-agent main --profile developer --working-dir ~/proj/myapp

The developer profile enables file editing, unrestricted shell access, and the full tool suite.

Run a one-shot task

Pass a prompt as a positional argument to run a single task and exit:

uv run rho-agent main "list all Python files that import asyncio"

Use a prompt template

Prompt files are markdown documents with YAML frontmatter for variables:

uv run rho-agent main --prompt examples/job-failure.md \
  --var cluster=prod \
  --var log_path=/mnt/logs/123

See Prompt Files for the full template format.

Connect to a database

Set the appropriate environment variables and the database tools become available automatically:

export SQLITE_DB=/path/to/data.db
uv run rho-agent main "list all tables and describe their schemas"

Database tools support PostgreSQL, MySQL, Oracle, Vertica, and SQLite. See Tools for configuration details.

Monitor running agents

# List running agents
uv run rho-agent ps

# Launch the observability dashboard
uv run rho-agent dashboard

# Open the interactive monitor
uv run rho-agent monitor

Next steps

  • Installation — all install methods and environment configuration
  • CLI Reference — complete command and flag documentation
  • Profiles — understand and customize capability profiles
  • Runtime API — embed agents in Python services