The Ren manual

Before you start

Requirements

Ren is a small FastAPI service that wraps Claude with on-device memory, a tool plugin layer and a stable cryptographic identity. It runs comfortably on hardware you already own.

• Python 3.12+ — tested on Apple Silicon Macs and Linux x86-64 (NUC-class hardware).
• No GPU. All language inference goes to the Anthropic API. The optional voice stack runs on CPU.
• An Anthropic API key for chat. Local features (memory, threads, home polling) work without one.
• uv for dependency management, or Docker if you prefer the container path.

Setup

Install

Ren uses uv for a fast, reproducible virtualenv. If you do not have it yet:

curl -LsSf https://astral.sh/uv/install.sh | sh

Then, from the repo root, three commands get you running:

make install          # uv sync --extra dev — creates .venv, installs deps
cp .env.example .env  # then add your ANTHROPIC_API_KEY
make run              # serves on http://127.0.0.1:8000

Setup

Configure

Ren reads settings from environment variables or a local .env file. Copy .env.example to .env and set at least your key:

ANTHROPIC_API_KEY=sk-ant-...

Core

Files & safety

Persona

Voice

Off by default and fully opt-in — see Voice setup below for the full walkthrough.

Home & connectors

Start with the provider switch REN_HOME_PROVIDER ("" off, homeassistant, or webhook). On top of that, Ren ships 18+ direct connectors — Hue, HomeKit, Matter, Z-Wave, Sonos, Roku, SmartThings, EVs and more — each with its own REN_* variables. Rather than reproduce all forty here, the full per-connector table lives on the API page.

Operate

Run

Start the server, then confirm it is alive. /health always responds and reports whether an API key is configured:

make run                       # http://127.0.0.1:8000

curl -s localhost:8000/health  # {"status":"ok","version":"1.0.0","has_api_key":true}

Talk to Ren over HTTP, or stream tokens over SSE:

curl -s localhost:8000/chat -H 'content-type: application/json' \
  -d '{"message":"hello ren"}'

curl -Ns localhost:8000/chat/stream -H 'content-type: application/json' \
  -d '{"message":"count to three"}'   # token-by-token SSE

Pass "tier": "fast" | "default" | "hard" in the body to override the model for a single turn. From conversation a pilot can build out a whole home — see the endpoint reference for the full surface (/identity, /memory, /threads, /ws/audio).

Operate

Docker

The repo ships a multi-stage Dockerfile (Python 3.12-slim, non-root user) and a docker-compose.yml. Set your key in .env, then:

cp .env.example .env            # set ANTHROPIC_API_KEY
docker compose up -d            # build + start on :8000

# optional: bring up a Home Assistant sidecar too
docker compose --profile ha up -d

In the container, Ren binds 0.0.0.0:8000 and persists everything to the ren_data volume mounted at /data — so REN_DB_PATH is /data/ren.db and REN_FILES_ROOT is /data/files. A built-in healthcheck polls /health every 30s. Build the image on its own with make docker.

Optional

Voice setup

Voice is opt-in. The STT/TTS/VAD models load only when enabled, so Ren boots fine without the ML dependencies installed (it just reports voice unavailable). To turn it on, add to .env:

REN_VOICE_ENABLED=true

# optional tuning
REN_VOICE_WAKE_ENABLED=false           # continuous wake-word listening
REN_VOICE_STT_MODEL=tiny               # Whisper size
REN_VOICE_TTS_VOICE=en_US-lessac-medium
REN_VOICE_VAD_THRESHOLD=0.5            # Silero sensitivity

Restart Ren, then open http://127.0.0.1:8000/ for the built-in push-to-talk web client, or connect your own client to the ws://127.0.0.1:8000/ws/audio WebSocket. Speech-to-text uses Whisper, text-to-speech uses Piper, and voice-activity detection uses Silero VAD — all server-side and CPU-only.

Connect

Smart home quickstart

The fastest path is a local Philips Hue bridge — two variables and you are controlling lights. Add to .env:

REN_HUE_URL=http://192.168.1.x    # your bridge IP
REN_HUE_USERNAME=your-hue-api-token

Restart Ren and say (or POST) "show me my smart home accessories" — your Hue lights appear. From there you can assign devices to rooms, group them into scenes, and write automations that reference them by name:

"Add a room called Living Room."
"Assign the lamp to the living room."
"Create a scene called Movie Night that dims the lights."
"Run Movie Night at 8pm every evening."

Persist your setup across restarts by pointing the path vars at real files: REN_HOME_GRAPH_PATH, REN_HOME_SCENES_PATH, REN_HOME_AUTOMATIONS_PATH (unset = in-memory only). Stuck? Say "run a health check on Ren" and it reports which connectors initialized. Every other platform — Home Assistant, HomeKit, Matter, Z-Wave, Sonos, Roku, SmartThings, EVs and more — is configured the same way; see the connector reference.

Trust

Data & privacy

Ren is local-first by construction. Everything it remembers stays in files on the machine you run it on:

• ./data/ren.db — a standard SQLite file holding all conversation memory, threads and reminders (path set by REN_DB_PATH). Open it with any SQLite browser; copy it to back up.
• ./data/ren_identity.key — Ren's persistent keypair, the seam for a future trust network.
• ./data/files — the sandbox the file tools are confined to (REN_FILES_ROOT). Path traversal outside it is refused; nothing is written elsewhere.