Clira is an AI executive agent that handles your email, calendar, and messaging across WhatsApp and Telegram. It prepares actions and drafts, but nothing executes without your approval. Self-hosted, open source, and architecturally designed so the AI cannot hallucinate facts into your outbox.

Highlights

  • Multi-channel agent across WhatsApp, Telegram, SMS, and web chat
  • Nothing sends without explicit approval
  • Planner/style architecture where the style layer cannot introduce facts
  • Extensible through MCP server connections and user-authored skills
  • Self-hosted with Docker Compose so your runtime and data stay under your control
  • Gmail ingestion in push and pull modes with deterministic pre-filtering

Architecture At A Glance

Clira is easiest to understand as two tightly connected systems: a multi-channel executive agent runtime that works across inbox, calendar, memory, and messaging context without bypassing approvals, and a draft-first reply pipeline that handles email as one capability inside that broader product.

Executive Agent Runtime

The executive agent is not just "chat with tools." It runs inside a deterministic policy envelope that decides what tools can exist, when the agent must pause for approval, and when a rerun is allowed with broader capabilities.

Reply Pipeline

This path is intentionally strict: deterministic filtering first, then a schema-validated LLM gate, then a planner/style split where the style stage is not allowed to add facts.

For the code-level component map and file references behind these diagrams, see docs/architecture.md.

Product Views

Clira full queue

Queue view with actionable drafts

Clira reply modal

Reply review modal before approval

Fast Self-Host

This is the default launch path. It assumes Docker and Docker Compose are installed.

  1. Clone the repo and copy the environment template.
cp .env.example .env
  1. Initialize local runtime state and generated secrets.
npm run selfhost:init

If you do not want to use npm, run bash scripts/selfhost-init.sh directly.

  1. Configure Gmail Pub/Sub and write the generated values back into .env.
npm run setup:google -- --project-id YOUR_PROJECT_ID --mode pull --write-env
  1. Fill in the remaining required values in .env.
  • GOOGLE_CLIENT_ID
  • GOOGLE_CLIENT_SECRET
  • your AI provider key
  1. Pull and start the default launch stack.
npm run selfhost:up
  1. Open Clira.

Image Tags

Clira publishes two kinds of image tags:

  • main and sha-<commit> for continuous builds from the main branch
  • vX.Y.Z, vX.Y, and latest for release tags such as v0.1.0

For evaluation and internal testing, the default CLIRA_IMAGE=ghcr.io/rushik-b/clira:main is fine. For production or any install you want to keep stable, pin CLIRA_IMAGE to an exact release tag in .env.

What Starts By Default

npm run selfhost:up starts the core profile:

  • app
  • worker
  • gmail-pull-worker
  • cron
  • db
  • redis

backfill-worker is intentionally not part of the default launch profile. Add it only when you want inbox search backfill:

npm run selfhost:up:full

Required Environment Values

Minimum first-run values live at the top of .env.example. The important ones are:

  • APP_PUBLIC_URL
  • NEXTAUTH_SECRET
  • CRON_SECRET
  • EMAIL_ENCRYPT_SECRET
  • EMAIL_ENCRYPT_SALT
  • GOOGLE_CLIENT_ID
  • GOOGLE_CLIENT_SECRET
  • GMAIL_PUBSUB_TOPIC
  • GMAIL_PUBSUB_PULL_SUBSCRIPTION
  • GOOGLE_APPLICATION_CREDENTIALS
  • AI_PROVIDER
  • provider auth for the selected model backend

Clira stores local runtime secrets under .clira-runtime/. The default Gmail service-account file path is ./.clira-runtime/google-service-account.json.

Self-Host Commands

Command What it does
npm run selfhost:init Creates .env if missing, generates secrets, creates .clira-runtime, and runs diagnostics
npm run selfhost:doctor Read-only diagnostics for env, Docker, ports, Gmail credentials, and AI provider config
npm run selfhost:up Pulls and starts the default core self-host profile
npm run selfhost:up:full Pulls and starts core plus backfill-worker
npm run selfhost:down Stops the self-host stack
npm run selfhost:logs Tails the main self-host services
npm run setup:google Provisions Gmail Pub/Sub resources and optional .env updates

Contributor Workflow

If you are developing Clira rather than just hosting it, use docs/setup.md. That doc covers:

  • local npm run dev
  • worker processes in separate terminals
  • local builds with docker-compose.dev.yml
  • contributor-oriented verification

AI Provider Notes

Google remains the default provider. The OpenRouter env names are still used for compatibility, but OPENROUTER_BASE_URL can point at any OpenAI-compatible endpoint. That includes OpenRouter, LM Studio, vLLM, and similar gateways. Details live in docs/ai-providers.md.

Documentation