# 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](#install-openrath-from-pypi) |
| Modify OpenRath source, run tests, or build docs | [Install from source for development](#install-from-source-for-development) |
| Use persistent memory | [Configure Memory](#configure-memory) |
| Use a container sandbox backend | [Launch and connect OpenSandbox](#launch-and-connect-opensandbox) |
| Use OpenViking memory | [Launch and connect OpenViking](#launch-and-connect-openviking) |

(install-openrath-from-pypi)=
## 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.

```bash
pip install openrath
```

If you manage your project environment with `uv`:

```bash
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:

1. `Provider(...)` fields.
2. Environment variables.
3. `~/.openrath/config.json` or `$OPENRATH_HOME/config.json`.

```bash
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:

```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:

```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:

```bash
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:

```python
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)=
## 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:

```python
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`:

```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:

```bash
python example/09_memory.py
```

(install-from-source-for-development)=
## Install from source for development
This is the developer installation path. Use it to modify OpenRath source, run tests, build docs, or debug examples.

```bash
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:

```bash
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
bash scripts/run_openrath_test.sh
```

Build the docs:

```bash
bash scripts/build_docs.sh
```

Or call Sphinx directly:

```bash
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:

```bash
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)=
## 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:

```bash
pip install "openrath[opensandbox]"
```

When using a source development environment:

```bash
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
bash scripts/launch_opensandbox.sh
```

Windows:

```bat
scripts\launch_opensandbox.bat
```

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

```bash
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.

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

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

```bash
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:

```bash
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:

```bash
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:

```bash
python example/03_sandbox_backend.py opensandbox
```

You can also bind directly in Python:

```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)=
## Launch and connect OpenViking
OpenViking is an optional memory backend. The base `local` memory backend does not require it.

Install the extra:

```bash
pip install "openrath[openviking]"
```

When developing from source, use the repository scripts:

```bash
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.