Documentation

Welcome to the openaur documentation. Here you'll find everything you need to get started, from installation to advanced usage.

Installation

openaur runs in Docker containers. This is the recommended and only supported installation method.

Prerequisites

• Docker Engine 20.10+
• Docker Compose 2.0+
• OpenRouter API key (get one free at openrouter.ai)

Automated Installation (Recommended)

The easiest way to install openaur is with our one-line installer:

curl -fsSL https://raw.githubusercontent.com/mattstyles333/openaur/master/install.sh | bash

The installer will:

• Check prerequisites (Docker, Docker Compose)
• Prompt for your OpenRouter API key
• Clone the repository
• Build Docker images
• Start all services
• Verify the installation

Manual Installation

If you prefer to install manually:

# 1. Clone the repository
git clone https://github.com/mattstyles333/openaur.git
cd openaur

# 2. Copy environment template
cp .env.example .env

# 3. Edit .env and add your API key
# OPENROUTER_API_KEY=your_key_here

# 4. Build and start containers
docker-compose up -d

# 5. Verify installation
make test
# Should show: {"status": "healthy", ...}

Configuration

Configuration is handled through environment variables in the .env file.

Quick Start

1. Register CLI Tools

openaur can learn about your CLI tools and their documentation:

# Crawl git's documentation
make crawl BINARY=git

# Now openaur knows every git command
make chat MSG="How do I undo my last 3 commits safely?"

2. Search and Install Packages

# Search Arch repos + AUR
make search QUERY=docker

# Install from AUR
make install PACKAGE=neovim-git

3. Interactive Chat

# One-shot chat
make chat MSG="What's installed on my system?"

# Or use the CLI directly
openaur chat

Cognitive Memory

openaur uses OpenMemory to persist context across sessions. Unlike other AI assistants that forget everything when you close the tab, openaur remembers:

• Conversations - Context from previous chats
• Preferences - How you like things configured
• System State - What packages are installed, configurations
• Actions - CLI tools you've registered and their usage patterns
• Relationships - Connections between different tools and concepts

Memory API

# Get memory stats
curl http://localhost:8000/memory/stats

# Query memories
curl -X POST http://localhost:8000/memory/query \
  -H "Content-Type: application/json" \
  -d '{"query": "nginx configuration"}'

# Add a memory
curl -X POST http://localhost:8000/memory/add \
  -H "Content-Type: application/json" \
  -d '{
    "content": "User prefers vim over emacs",
    "category": "preferences",
    "tags": ["editor", "vim"]
  }'

Empathy Engine

openaur analyzes your sentiment and adapts its tone accordingly. This makes interactions feel more natural and supportive.

How It Works

When you send a message, openaur:

1. Analyzes sentiment (positive, negative, neutral)
2. Detects emotions (frustrated, excited, confused, etc.)
3. Adjusts response tone to match your emotional state

Example Responses

Check Empathy Status

curl http://localhost:8000/heart
# Returns: {"mood": "focused", "tone": "technical", "empathy_level": 0.8}

Action Registry

The Action Registry is where openaur stores information about CLI tools. When you "crawl" a binary, openaur:

1. Reads the man page
2. Runs --help and -h
3. Explores subcommands with BFS (breadth-first search)
4. Stores all documentation in YAML format

Registering Tools

# Using make
make crawl BINARY=docker
make crawl BINARY=kubectl
make crawl BINARY=ffmpeg

# Using API directly
curl -X POST http://localhost:8000/actions/crawl \
  -H "Content-Type: application/json" \
  -d '{"binary": "git"}'

Recommended CLI tools to register:

# Cloud & Infrastructure
make crawl BINARY=aws          # AWS CLI
make crawl BINARY=kubectl      # Kubernetes
make crawl BINARY=terraform    # Infrastructure as code

# Development Tools
make crawl BINARY=gh           # GitHub CLI
make crawl BINARY=opencode     # AI coding agent
make crawl BINARY=playwright   # Browser automation

# Security & Secrets
make crawl BINARY=op           # 1Password CLI

# System Tools
make crawl BINARY=yay          # AUR helper
make crawl BINARY=systemctl    # systemd services

Listing Registered Actions

curl http://localhost:8000/actions/
# Returns list of all registered CLI tools

Sub-Agents

Sub-agents are specialized AI instances that run in isolated tmux sessions. Each agent has its own context, memory, and tool access.

Use Cases

• Long-running tasks that shouldn't block the main assistant
• Parallel processing of multiple requests
• Isolated experimentation without affecting main context
• Specialized agents for different domains (security, DevOps, etc.)

Registering an Agent

curl -X POST http://localhost:8000/agents/register \
  -H "Content-Type: application/json" \
  -d '{
    "id": "security-auditor",
    "name": "Security Auditor",
    "description": "Specialized in security analysis",
    "system_prompt": "You are a security expert. Focus on vulnerabilities...",
    "model": "openrouter/auto",
    "tools": ["nmap", "openssl", "gpg"]
  }'

Spawning an Agent

curl -X POST http://localhost:8000/agents/spawn \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "security-auditor",
    "task_description": "Audit nginx configuration for security issues",
    "task_context": {"config_path": "/etc/nginx/nginx.conf"}
  }'

Chat API

openaur provides both OpenAI-compatible endpoints and enhanced chat endpoints.

OpenAI-Compatible

curl -X POST http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -d '{
    "model": "openrouter/auto",
    "messages": [
      {"role": "user", "content": "Hello!"}
    ]
  }'

Enhanced Chat (with Memory)

curl -X POST http://localhost:8000/chat \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What's the status of my system?",
    "session_id": "optional-session-id",
    "include_memory": true,
    "empathy_mode": true
  }'

Memory API

Packages API

Agents API

Actions API

CLI: Server Commands

# Start openaur containers
openaur server start

# Stop containers
openaur server stop

# View logs
openaur server logs

# Check status
openaur server status

CLI: Chat

# Interactive chat mode
openaur chat

# One-shot message
openaur chat "How do I configure nginx with SSL?"

CLI: Packages

# Search packages
openaur packages search neovim

# Install a package
openaur packages install neovim-git

# List installed
openaur packages list

CLI: Actions

# List registered actions
openaur actions list

# Crawl a new binary
openaur actions crawl kubectl

# Show action details
openaur actions show docker

Architecture

openaur follows a modular microservices architecture built on Arch Linux.

┌─────────────────────────────────────────────────────────────────┐
│                         openaur                                │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│   ┌──────────┐    ┌───────────┐    ┌──────────────────────┐   │
│   │  Client  │───▶│  FastAPI  │───▶│    LLM Gateway       │   │
│   │ (CLI/UI) │    │  Gateway  │    │   (OpenRouter)       │   │
│   └──────────┘    └───────────┘    └──────────────────────┘   │
│                            │                                     │
│        ┌───────────────────┼───────────────────┐                 │
│        ▼                   ▼                   ▼                 │
│   ┌──────────┐      ┌──────────┐      ┌──────────────┐       │
│   │ OpenMemory│      │  Agents  │      │ Action Reg     │       │
│   │ (SQLite)  │      │ Service  │      │  (YAML)        │       │
│   └──────────┘      └──────────┘      └──────────────┘       │
│                            │                                     │
│        ┌───────────────────┼───────────────────┐                 │
│        ▼                   ▼                   ▼                 │
│   ┌──────────┐      ┌──────────┐      ┌──────────────┐       │
│   │ Empathy  │      │  Email   │      │ Arch Linux   │       │
│   │ Engine   │      │ Service  │      │ + AUR (yay)  │       │
│   └──────────┘      └──────────┘      └──────────────┘       │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Key Components

• FastAPI Gateway - REST API with async request handling
• OpenMemory - Cognitive memory layer with SQLite persistence
• Empathy Engine - Real-time sentiment analysis
• Agent Service - Sub-agent management and tmux execution
• Package Manager - Arch/AUR integration via yay
• Action Registry - YAML-based CLI tool documentation

Development

Building Locally

# Build containers
make build

# Run with attached logs
make run-logs

# Shell into container
make shell

# View logs
make logs

# Reset database
make reset-db

Code Style

See AGENTS.md for detailed code style guidelines. Quick summary:

• Use ruff for linting and formatting
• Absolute imports only (from src.models...)
• Type hints on all public functions
• Max 100 characters per line

Acknowledgments

openaur stands on the shoulders of these incredible open source projects:

Core Stack

• FastAPI - High-performance web framework
• Typer - CLI framework
• Pydantic - Data validation
• SQLAlchemy - Database toolkit
• Uvicorn - ASGI server

Terminal & UI

• Rich - Terminal formatting
• Open WebUI - Web interface companion

AI & Memory

• OpenRouter - Universal LLM API
• OpenMemory - Cognitive memory layer

System Tools

• tmux - Terminal multiplexer
• yay - AUR helper
• Arch Linux - Foundation OS
• Docker - Container platform
• psutil - System monitoring

Python Ecosystem

• httpx - HTTP client
• PyYAML - YAML parsing
• python-jose & passlib - Security
• aiofiles - Async file operations

To all open source maintainers: thank you for sharing your work.

Troubleshooting

Container Won't Start

API Connection Refused

Permission Denied (Package Install)