iris

# Iris Iris is an LLM-first, source-agnostic messaging system designed to unify messages from multiple platforms—Telegram, SMS, Email, WhatsApp, Instagram, and others—into a single, queryable API. It is self-hostable, MIT-licensed, and built in Rust. ## Key Features - **Unified Model**: Normalizes all messages into consistent `Message`, `Thread`, and `Contact` structures. - **Source-Agnostic Queries**: Query across all sources without knowing their origin (e.g., "all unread threads"). - **LLM-First Design**: Optimized for agent consumption with MCP support, structured JSON, and capability advertisement. - **Code Generation**: CLI, HTTP, and MCP surfaces are generated from a single API definition, ensuring consistency. - **Self-Hostable**: No cloud dependencies; runs anywhere Rust runs. - **Extensible**: Adding a new provider requires implementing a single trait. ## Quick Start ```bash cargo build cargo run -- threads cargo run -- messages <thread-id> cargo run -- contacts cargo run -- serve ``` ## Self-Hosting with Docker Published images are available at `ghcr.io/techgodhq/iris:<version>` (or `:latest`). Set `IRIS_API_TOKEN` to a high-entropy secret for internet-reachable deployments; all HTTP endpoints except `GET /health` require Bearer token authentication. Without a token, the server refuses public or wildcard bind addresses. Example: ```bash docker run --rm \ --name iris \ --publish 127.0.0.1:9876:9876 \ --volume iris-data:/data \ --env IRIS_ENABLED_PROVIDERS=telegram \ --env IRIS_TELEGRAM_BOT_TOKEN="${IRIS_TELEGRAM_BOT_TOKEN}" \ ghcr.io/techgodhq/iris:latest ``` ## Configuration Iris supports TOML files, native environment variables, or both. Environment values override TOML, which overrides defaults. Key variables include `IRIS_ENABLED_PROVIDERS`, `IRIS_TELEGRAM_BOT_TOKEN`, and various `IRIS_EMAIL_*` settings. Multiple instances of a provider type are supported (e.g., `email.ops-codefold`), with independent configuration and environment variable naming conventions. ## Architecture Iris is structured as a workspace with crates: - `iris-core`: Domain model and `MessageProvider` trait (zero I/O dependencies) - `iris-providers`: Provider implementations (Telegram, SMS, Email, etc.) - `iris-server`: Axum HTTP server (REST API) - `iris-cli`: Command-line interface (clap) - `iris-mcp`: MCP server surface - `iris-codegen`: Code generation to keep CLI/HTTP/MCP in sync ## Adding a Provider 1. Create a module in `iris-providers/src/`. 2. Implement the `MessageProvider` trait. 3. Register it in server/CLI startup. ## Development ```bash cargo build --all-targets cargo test --all-targets cargo clippy --all-targets -- -D warnings cargo fmt --all -- --check ``` Pre-commit hooks are configured via lefthook. ## License MIT