Warren

Talk to your AI agents from a Rabbit R1.

Warren bridges the R1's voice PTT and WebView interfaces to an arbitrary personal AI agent. A FastAPI server handles auth, session management, and event routing, and proxies sessions to an agent over a WebSocket protocol (or to local Orca terminals). An R1 Creation provides the 240x282 terminal UI.

R1 PTT (Voice) ───────WebSocket───┐
                                   ├── Warren ──WebSocket──▶ Personal Agent
R1 Creation (240x282 WebView) ─SSE┘

The agent connects to Warren as a client, so it can run behind NAT/firewalls with no public webhook. See PROTOCOL.md and examples/agent.py.

Prerequisites

• A personal AI agent that speaks the Warren WebSocket protocol (see examples/agent.py)
• Rabbit R1 (or any browser for testing)
• A server reachable over HTTPS (required for R1 WebView and voice)

Setup

Docker Compose (recommended)

git clone https://github.com/dsr-restyn/warren.git
cd warren

Set required environment variables:

export WARREN_ADMIN_TOKEN=your-secret-admin-token
export WARREN_INTERNAL_SECRET=your-agent-auth-secret

Start Warren:

docker compose up -d

Then connect your agent to wss://your-server/api/agent/ws?token=$WARREN_INTERNAL_SECRET.

Put a reverse proxy (nginx, Caddy, Traefik) in front of port 4030 to terminate TLS.

Bare metal

git clone https://github.com/dsr-restyn/warren.git
cd warren/server
uv sync
cp config.yaml.example config.yaml
# Edit config.yaml: add your repo paths

export WARREN_ADMIN_TOKEN=your-secret-admin-token
export WARREN_INTERNAL_SECRET=your-agent-auth-secret
uv run python -m warren
# Listens on 0.0.0.0:4030

Pairing your R1

1. Navigate to https://your-server/admin in a browser and enter your admin token.
2. Go to /install/qr to generate a pairing QR code.
3. Scan the QR code with your R1. The Warren Creation loads in the R1 WebView.

For voice PTT pairing: GET /pair/voice/qr generates a QR for the R1's native voice assistant.

Usage

• Voice (primary) — press and hold the R1 PTT button, speak your request. Sessions are created automatically.
• Creation UI — monitor active sessions, view tool use output, access command palette.
• Command palette — tap [CMD] for quick actions and prompt templates defined in config.yaml.

Sessions auto-transition based on inactivity: active → idle → suspended → terminated. Thresholds are set in config.yaml.

Environment Variables

Variable	Default	Description
WARREN_ADMIN_TOKEN	(required)	Token for admin operations (pairing, config)
WARREN_INTERNAL_SECRET	(recommended)	Token required of agents connecting to /api/agent/ws
WARREN_BACKEND	websocket	Backend adapter: websocket (default) or orca (experimental, single local terminal)
WARREN_CONFIG	config.yaml	Path to YAML config file
WARREN_DB	warren.db	Path to SQLite database
WARREN_HOST	0.0.0.0	Server bind address
WARREN_PORT	4030	Server port
WARREN_VOICE_ENABLED	false	Enable voice WebSocket endpoint
WARREN_VOICE_PORT	443	Port advertised in voice pairing QR

Configuration

Copy server/config.yaml.example to config.yaml and edit it:

# Repositories Warren can access.
# git_url is optional (used for auto-clone on container start).
repos:
  my-project:
    path: /home/user/projects/my-project
    git_url: git@github.com:user/my-project.git

# Command palette entries shown in the R1 UI.
commands:
  actions:
    - label: RUN TESTS
      prompt: run the test suite
    - label: LINT
      prompt: run the linter and fix any issues
  templates:
    - label: FIX BUG
      prompt: "fix the bug in {description}"
    - label: ADD FEATURE
      prompt: "implement {description}"

# Session limits and lifecycle timeouts
max_concurrent_sessions: 4
idle_timeout_minutes: 10
suspend_timeout_hours: 2
cleanup_days: 7

Development

cd server
uv sync --extra dev

uv run ruff check src/ tests/   # Lint
uv run pytest tests/ -v         # Unit tests

Architecture

File	Purpose
server/src/warren/app.py	FastAPI app, endpoints, SSE streaming
server/src/warren/adapters/websocket.py	WebSocket agent proxy adapter (default)
server/src/warren/adapters/orca.py	Local Orca terminal adapter (experimental, single-session)
server/src/warren/voice.py	Voice WebSocket handler (OpenClaw protocol)
server/src/warren/bus.py	SessionBus pub/sub (multi-consumer events)
server/src/warren/lifecycle.py	Background session lifecycle sweep
server/src/warren/auth.py	QR pairing, device tokens
server/src/warren/db.py	SQLite (sessions, tokens, messages)
server/src/warren/config.py	pydantic-settings + YAML config
creation/	R1 WebView (vanilla HTML/CSS/JS)
PROTOCOL.md	WebSocket agent protocol reference
examples/agent.py	Reference Python agent client

License

MIT