---
slug: "roo-roo"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/MLAI-AUS-Inc/roo@main/README.md"
repo: "https://github.com/MLAI-AUS-Inc/roo"
source_file: "README.md"
branch: "main"
---
# Roo Standalone - AI Agent Service

A standalone FastAPI microservice for the Roo AI agent with PostgreSQL + pgvector for vector embeddings and a skills-based architecture.

## Quick Start

```bash
# Install dependencies
pip install -r requirements.txt

# Run development server
uvicorn roo.main:app --reload

# Run with Docker
docker-compose up -d
```

## Project Structure

```
roo-standalone/
├── roo/                    # Main application
│   ├── main.py             # FastAPI entrypoint
│   ├── config.py           # Settings
│   ├── agent.py            # Core agent
│   ├── llm.py              # LLM client
│   ├── database.py         # PostgreSQL + pgvector
│   ├── embeddings.py       # Vector embeddings
│   ├── slack_client.py     # Slack SDK
│   ├── skills/             # Skill system
│   └── clients/            # External API clients
├── skills/                 # Skill definitions (*.md)
├── tests/                  # Test suite
└── docker-compose.yml
```

## Skills System

Skills are defined as markdown files in `skills/`. Each skill specifies:
- Trigger keywords
- Parameters to extract
- Actions to perform (LLM, database, API calls)

See `skills/connect_users.md` for an example.

## Environment Variables

Copy `roo-standalone/.env.example` to `roo-standalone/.env` and configure:
- `DATABASE_URL` - PostgreSQL connection
- `SLACK_BOT_TOKEN` - Slack bot token
- `OPENAI_API_KEY` - For LLM and embeddings
- `MLAI_BACKEND_URL` - Backend API URL for points, admin lookup, and Luma attendee reports
- `ROO_API_KEY`/`MLAI_API_KEY`/`INTERNAL_API_KEY` - Backend auth key for Roo-to-mlai-backend calls

For Slack file parsing, the Roo Slack app must include the `files:read` bot scope. Contextual Linear commands additionally require `channels:history`/`channels:read` for public channels, `groups:history`/`groups:read` for private channels, and `users:read` plus `users:read.email` for reliable Slack-to-Linear identity matching. Reinstall the app after adding scopes. If Slack rotates the bot token during reinstall, update `SLACK_BOT_TOKEN` in production and restart Roo.

For daily jobs, the recommended production setup is:
- `mlai-backend` owns the 7am Melbourne scheduler and Slack posting
- Roo keeps `JOBS_SCHEDULER_ENABLED=false`
- Roo only needs `JOBS_API_URL` and `JOBS_TRIGGER_TOKEN` if you want it to trigger backend jobs manually in the future