Caelo

✨ What is Caelo?

Caelo is an independent, open-source desktop client for the xAI Grok API. Instead of five separate tools, it puts the entire Grok surface behind one shared backbone — context, history, projects and cost flow across every mode:

💬 Chat  ·  🎨 Image & Video  ·  🎙️ Voice  ·  ⌨️ Agentic coder  ·  🧩 Extensions

It's bring-your-own-key: you supply your own xAI credentials, they stay on your machine, and they're sent only to api.x.ai. No accounts, no middleman, no telemetry.

🚀 Highlights

🖼️ Take a look

🧭 The modules

• 💬 Chat — streaming multi-conversation chat with a model picker, system prompt & temperature, markdown + code, attachments (image/file), live web/X search, vision, document Q&A with citations, and voice (TTS replies + STT dictation).
• ⌨️ Code — a mini-IDE: file tree, CodeMirror editor, terminal, and an agent with file tools and approval cards (Accept / Reject / Always) + diff preview, checkpoints/undo, plan mode, per-project rules (CAELO.md), and subagent teams with merge review.
• 🎨 Image — generate and edit images in one panel (no refs → generate, with refs → edit), model picker, and variations.
• 🎬 Video — text→video and image→video generation, plus edit and extend.
• 🎙️ Voice — Speak (TTS), Transcribe (STT), Talk (voice conversation), and Live (realtime).
• 🗂️ History & Gallery — a searchable artifact & generation history (SQLite + FTS5), scoped to projects; send artifacts between modes, and reuse the prompt behind any generated image or video with one click.
• 🧩 Extensions — MCP servers, slash commands, hooks, skills, and a package marketplace.

🔐 Privacy & security

Caelo is a normal desktop app — a Windows GUI you install from a signed .exe and click around in. (There's a Python backend bundled inside the installer, but you never see a terminal.) It is local-first and sends no telemetry — no analytics endpoint, no usage reporting, no phoning home. A fresh install talks only to api.x.ai (with your key, for the features you use) and to GitHub Releases (to check for updates — skippable).

Where your data goes:

   You ──▶ Caelo (your PC) ──▶ api.x.ai   ← the only outbound destination
                  │
                  └──▶ GitHub Releases (update check only — can be skipped)

• Backend listens on 127.0.0.1 (localhost) only — never exposed to the network.
• REST requires Authorization: Bearer <token>; WebSockets take the token via query — both fail-closed.
• The xAI bearer token is sent only to api.x.ai and never reaches the renderer; it is stored locally and never returned by the local API.
• Agent file operations are sandboxed to the workspace; writes and shell commands require approval, and run with a secret-free environment.

What Caelo does not do:

• ❌ No telemetry, analytics, or tracking of any kind.
• ❌ No third-party servers — nothing is sent anywhere except xAI's own API.
• ❌ No account, no sign-up, no middleman — it's bring-your-own-key.
• ❌ Your key, chats, files, and generations never leave your machine (except your prompts to xAI, which Grok needs to answer them).

Don't trust — verify. Caelo is fully open source under Apache-2.0. Read the code, or just watch the traffic: with the app running, api.x.ai is the only outbound connection you'll see.

Report vulnerabilities privately — see SECURITY.md.

⬇️ Install

For users — grab the file for your platform from the latest release, run it, then open Settings and sign in with your xAI account or paste an API key. That's it.

macOS is Apple Silicon only. The .dmg is built and notarized on an Apple Silicon Mac. Intel (x64) builds aren't published — there's no Intel Mac to build and verify the native Python sidecar (tracked in docs/plans/PLAN_OTWARTE.md). On Apple Silicon, run the .dmg; on Linux, the .AppImage is portable (chmod +x and run) or install the .deb.

Requirements: Node.js ≥ 20 (tested on v22) · Python 3.10+ · an xAI account or API key.

# 1) Backend (caelo_core) — isolated venv
cd caelo_core
python -m venv .venv
.venv\Scripts\pip install -r requirements.txt
#   behind a TLS-intercepting proxy, add:  --trusted-host pypi.org --trusted-host files.pythonhosted.org
cd ..

# 2) Frontend (desktop)
cd desktop
npm install
npm run dev      # launches the Electron window and spawns the backend

npm run dev starts electron-vite (HMR); the main process spawns the sidecar, reads the handshake (port + token), and connects over 127.0.0.1. Python is located via CAELO_CORE_PYTHON (env) → caelo_core/.venv/Scripts/python.exe → system python.

Auth precedence: OAuth access token → saved API key → XAI_API_KEY from .env.

# Build the Windows installer
cd desktop
npm run dist:full      # PyInstaller sidecar + electron-builder NSIS → desktop/dist/Caelo-Setup-*.exe

# Backend self-checks (mocks where xAI is needed), from the repo root
caelo_core\.venv\Scripts\pip install -r caelo_core\requirements-dev.txt   # one-time: pytest
caelo_core\.venv\Scripts\python -m pytest caelo_core\tests -v

# Frontend
cd desktop && npm run typecheck && npm run lint && npm test

The command above builds the Windows installer locally (signed with the maintainer's SimplySign cert). macOS (arm64 dmg, Developer ID + notarized) is likewise built locally on an Apple Silicon Mac — see docs/guides/MACOS_LOCAL_BUILD.md. Linux (AppImage/deb) is built in CI (a v* tag, or a manual workflow run). Per-release assembly — see docs/guides/RELEASING.md.

🏗️ Architecture

Electron (frontend) + Python sidecar (backend). The mature xAI logic (OAuth, SSE streaming, media) is reused, not rewritten.

┌──────────────────────── Electron (main process) ──────────────────────────┐
│  window, menu, IPC, sidecar lifecycle; spawns `python -m caelo_core`        │
│  handshake: generates a session token → CAELO_CORE_TOKEN; reads port/stdout │
│  preload (contextBridge) → window.caelo ; Renderer: React 19 + TypeScript    │
│  Modules: Chat · Code (mini-IDE) · Image · Video · Voice · History · Settings │
└─────────────────────────────────────────────────────────────────────────────┘
              │  HTTP (REST) + WebSocket (streaming) — 127.0.0.1 only + token
              ▼
┌──────────────── Python backend "caelo-core" (FastAPI / uvicorn) ───────────┐
│  Reused xAI core: api_manager · oauth_manager · chats · history (repo root) │
│  Routes: /auth /models /settings /chat(WS) /images /video /voice(+WS)        │
│          /history /fs /git /permissions /agent(WS) /terminal(WS) /mcp …      │
│  Agent engine: file tools + workspace sandbox + approval gate + LLM loop     │
└─────────────────────────────────────────────────────────────────────────────┘
              │  Bearer (OAuth token / API key) — sent exclusively to api.x.ai
              ▼  xAI / Grok API

The architecture source of truth for contributors is CLAUDE.md.

📚 Documentation

• User Guide — every module, step by step.
• API reference — backend REST/WebSocket API (96 routes + 6 WS).
• CLAUDE.md — architecture source of truth + hardening history.
• Docs index · Changelog · Roadmap

🤝 Contributing

Contributions are welcome! See CONTRIBUTING.md and the CLA, and please follow the Code of Conduct.

☕ Support

Caelo is free and open source. If it's useful to you, you can support its development:

Every coffee helps keep the project maintained and the updates coming. Thank you! 💜

📄 License & trademarks

Licensed under Apache-2.0. © 2026 AuraVix Studio.

Caelo is an independent project and is not affiliated with, endorsed by, or sponsored by xAI. "Grok", "SuperGrok", and "xAI" are trademarks of xAI Corp; they are used here only to describe interoperability (see NOTICE).