Installation#

OpenRath supports CPython 3.10 through 3.13. Choose the installation path that matches your use case:

Goal	Path
Use OpenRath to build agent workflows	Install OpenRath from PyPI
Modify OpenRath source, run tests, or build docs	Install from source for development
Use persistent memory	Configure Memory
Use a container sandbox backend	Launch and connect OpenSandbox
Use OpenViking memory	Launch and connect OpenViking

Install OpenRath from PyPI#

This is the user installation path. It installs the OpenRath core runtime: Session, Workflow, FlowToolCall, the local backend, local memory, OpenAI-compatible and Anthropic LLM clients, persistent config, and the stdio MCP adapter.

pip install openrath

If you manage your project environment with uv:

uv add openrath

Core dependencies include:

Dependency	Purpose
`openai`	OpenAI-compatible chat client and Azure OpenAI routing.
`anthropic`	Anthropic Messages API adapter.
`mcp`	Stdio MCP server integration.
`pydantic`	Tool schemas, request/response models, and configuration types.

Configure the LLM#

Real LLM workflows require provider configuration. The most explicit path is to build a Provider with the API key, optional base URL, model, and provider kind. Clients resolve credentials in this order:

Provider(...) fields.
Environment variables.
~/.openrath/config.json or $OPENRATH_HOME/config.json.

export OPENAI_API_KEY=...
export OPENAI_BASE_URL=https://api.openai.com/v1
export OPENAI_DEFAULT_MODEL=gpt-5.5

export ANTHROPIC_API_KEY=...
export ANTHROPIC_DEFAULT_MODEL=claude-sonnet-4-5

Variable	Meaning
`OPENAI_API_KEY`	OpenAI or compatible gateway API key. The default client fails if this is missing.
`OPENAI_BASE_URL`	OpenAI-compatible endpoint.
`OPENAI_DEFAULT_MODEL`	OpenAI-compatible fallback model.
`AZURE_OPENAI_ENDPOINT`	Azure OpenAI endpoint fallback when `Provider.base_url` is empty.
`AZURE_OPENAI_API_KEY` / `AZURE_API_KEY`	Azure OpenAI key fallbacks.
`OPENAI_API_VERSION` / `AZURE_OPENAI_API_VERSION`	Legacy Azure API version; default is `2024-10-21`.
`ANTHROPIC_API_KEY`	Anthropic API key.
`ANTHROPIC_BASE_URL`	Optional Anthropic-compatible endpoint.
`ANTHROPIC_DEFAULT_MODEL`	Anthropic fallback model.

Persistent config is JSON:

{
  "version": 1,
  "llm": {
    "default_provider": "openai-main",
    "providers": {
      "openai-main": {
        "provider_kind": "openai",
        "model": "gpt-5.5",
        "api_key": "sk-..."
      }
    }
  },
  "memory": {
    "default_provider": "local-main",
    "providers": {
      "local-main": {
        "backend_kind": "local",
        "path": ".openrath/memory",
        "embedding_provider": "openai-main",
        "chat_provider": "openai-main"
      }
    }
  }
}

Use it from Python:

from rath.llm import Provider

provider = Provider.from_config("openai-main", temperature=0.2)

OpenRath does not auto-load .env files. Source them in the shell or let your deployment platform inject secrets before starting Python.

If you also cloned the OpenRath repository, you can first run examples that do not depend on OpenSandbox or a live model:

python example/02_session_lineage.py
python example/06_mcp_tool.py
python example/09_memory.py

When using OpenRath from PyPI in your own project, import it directly:

import os

from rath import flow
from rath.llm import Provider
from rath.session import Session

provider = Provider(
    api_key=os.environ["OPENAI_API_KEY"],
    base_url=os.environ.get("OPENAI_BASE_URL") or None,
    model=os.environ.get("OPENAI_DEFAULT_MODEL") or "gpt-5.5",
)

agent = flow.Agent("Use tools when helpful.", provider=provider)
user = Session.from_user_message("List files.").to("local", spec=".")
out = agent(user)

Configure Memory#

OpenRath v1.2.0 includes local memory in the base install. The local backend is registered as local, uses public memory:// URIs, stores data under .openrath/memory/ by default, and can run lexical BM25 recall without any LLM key.

The shortest path is:

from rath import flow

with flow.Agent("Remember useful facts.", model="demo", memory="local") as agent:
    agent.remember_memory("The user writes Python.")
    hits = agent.recall_memory("preferred programming language")

Configure named local memory stores in ~/.openrath/config.json:

{
  "version": 1,
  "memory": {
    "default_provider": "local-main",
    "providers": {
      "local-main": {
        "backend_kind": "local",
        "path": ".openrath/memory",
        "embedding_provider": "embed-main",
        "chat_provider": "chat-main"
      }
    }
  }
}

Field	Meaning
`backend_kind`	Currently `local` in config. OpenViking stores are opened explicitly or through adapter/environment settings.
`path`	Local memory root. Relative paths are resolved from the current project.
`embedding_provider`	Optional `llm.providers` entry used for embedding-ranked search.
`chat_provider`	Optional `llm.providers` entry used by commit-time memory extraction.

Run the key-free memory example from a source checkout:

python example/09_memory.py

Install from source for development#

This is the developer installation path. Use it to modify OpenRath source, run tests, build docs, or debug examples.

git clone https://github.com/Rath-Team/OpenRath.git
cd OpenRath
uv sync --group dev --group docs

Without uv, use an editable install. This also works in an existing mamba/conda environment:

pip install -e .
pip install pytest ruff mypy sphinx myst-parser pydata-sphinx-theme

Development dependencies include:

Dependency group	Contents
runtime	`openai`, `anthropic`, `mcp`, `pydantic`.
dev	`pytest`, `ruff`, `mypy`.
docs	`sphinx`, `myst-parser`, `pydata-sphinx-theme`.

Configure credentials in your shell, CI secret store, or deployment environment. OpenRath does not load repository-local secret files.

Run tests:

bash scripts/run_openrath_test.sh

Build the docs:

bash scripts/build_docs.sh

Or call Sphinx directly:

uv run sphinx-build -M html docs/source docs/_build

In a mamba environment that already has the docs dependencies installed, the equivalent direct build is:

mamba run -n rath-dev python -m sphinx -M html docs/source docs/_build

The generated output is under docs/_build/html/.

Launch and connect OpenSandbox#

OpenSandbox is an optional backend. It is useful for workflows that need a container execution environment. OpenRath connects to it with Session.to("opensandbox", spec=...); the default local backend does not require this step.

Install the OpenSandbox extra#

When using PyPI:

pip install "openrath[opensandbox]"

When using a source development environment:

uv sync --extra opensandbox

This extra installs:

Package	Purpose
`opensandbox`	OpenSandbox Python SDK.
`opensandbox-code-interpreter`	Code interpreter client.
`opensandbox-server`	Starts the OpenSandbox API server locally.

Start the service#

Local development usually starts OpenSandbox with the repository script. The script checks Docker, syncs the optional dependency, generates .sandbox.toml, adds the current OpenRath project directory to the host bind allowlist, and starts opensandbox-server. On macOS with Colima, if DOCKER_HOST is unset and the Colima socket exists, the script exports DOCKER_HOST=unix://${HOME}/.colima/default/docker.sock automatically.

macOS / Linux:

bash scripts/launch_opensandbox.sh

Windows:

scripts\launch_opensandbox.bat

The script uses the OpenSandbox Docker configuration example by default. Switch the packaged example with an environment variable:

SANDBOX_INIT_EXAMPLE=docker bash scripts/launch_opensandbox.sh

Allowed values include docker, docker-zh, k8s, and k8s-zh.

Check service status#

After the OpenSandbox server starts, first check that the control plane responds. /health is the unauthenticated health-check path for the OpenSandbox server.

curl -fsS http://127.0.0.1:8080/health

If curl is not installed, use Python for the same check:

python - <<'PY'
import urllib.request

with urllib.request.urlopen("http://127.0.0.1:8080/health", timeout=3) as resp:
    print(resp.status)
    print(resp.read().decode("utf-8", errors="replace"))
PY

The health check only confirms that the OpenSandbox API server responds locally. The container runtime, workspace bind, and OpenRath client configuration still need to be verified with the later example.

Connect OpenRath to OpenSandbox#

Set client variables in the environment where OpenRath runs:

export OPEN_SANDBOX_DOMAIN=127.0.0.1:8080
export OPEN_SANDBOX_API_KEY=

If the server sets an API key, the server and client values must match:

export OPENSANDBOX_SERVER_API_KEY=...
export OPEN_SANDBOX_API_KEY=...

Variable	Meaning
`OPEN_SANDBOX_DOMAIN`	OpenSandbox API server address. The local default is `127.0.0.1:8080`.
`OPEN_SANDBOX_API_KEY`	API key used by the OpenRath client when requesting the server.
`OPENSANDBOX_SERVER_API_KEY`	API key on the OpenSandbox server side.
`RATH_OPENSANDBOX_STRICT_WORKSPACE_BIND`	When set to `1`, a failed host bind does not fall back to an empty workspace.

Verify the backend#

After confirming that the server is listening locally, run the sandbox backend example:

python example/03_sandbox_backend.py opensandbox

You can also bind directly in Python:

from rath.session import Session

user = Session.from_user_message("List the workspace.")
user = user.to("opensandbox", spec=".")

spec="." requests a bind from the current directory to /workspace inside the container. This host path must be visible to the machine running the OpenSandbox server and allowed by the storage allowlist in .sandbox.toml. The repository script automatically allowlists the current project directory. To bind other directories, manually add the matching prefix to allowed_host_paths. If the host bind is rejected, OpenRath retries with an empty workspace by default. Set RATH_OPENSANDBOX_STRICT_WORKSPACE_BIND=1 to disable this fallback.

Local sandbox path notes#

Session.to("local", spec="...") treats the string spec as BackendSandboxSpec(working_dir=...). LocalBackend.close(...) only deletes temporary working directories that OpenRath created itself. User-supplied working directories are left on disk when the sandbox closes.

Launch and connect OpenViking#

OpenViking is an optional memory backend. The base local memory backend does not require it.

Install the extra:

pip install "openrath[openviking]"

When developing from source, use the repository scripts:

bash scripts/launch_openviking.sh
bash scripts/check_openviking.sh

OpenViking exposes a richer external memory service. OpenRath keeps the public memory API on memory:// URIs; the adapter translates to OpenViking’s internal viking:// boundary.