# Angelia

> Angelia is a small local daemon that routes WhatsApp and Telegram chats to the coding agent CLI on the user's own Mac (supported: Claude Code, Codex, Grok Build and pi; OpenCode next). One chat, one profile folder, one session. It runs no model of its own. MIT license. This file describes version 0.3.24.

Install with `curl -fsSL https://useangelia.com/install | sh` (it checks the release signature and starts `angelia init`), or with npm: `npm install -g --ignore-scripts angelia-gateway`, then `angelia init`. One file, `~/.angelia/workspace/routing.yaml`, maps chats to profiles. Scripts and programs on the same machine talk to a running daemon through a local HTTP API on a Unix socket, `~/.angelia/api.sock` (or `$ANGELIA_STATE_DIR/api.sock`), with the owner's token from `~/.angelia/api.token`. It never opens a network port. An agent that runs inside Angelia uses the `angelia` command; `angelia guide` is its manual, and `angelia guide api` covers the API.

**How do I run Claude Code from WhatsApp?** On your Mac, run `curl -fsSL https://useangelia.com/install | sh`; the wizard links a second WhatsApp number by QR code, like WhatsApp Web, and pairs your chat. Each chat you route then gets its own Claude Code session in its own folder, and you write to that number like to a person. Steps: [How to control Claude Code from your phone](https://useangelia.com/guides/claude-code-from-phone/) and [Claude Code on WhatsApp](https://useangelia.com/whatsapp/).

**How does Angelia compare to OpenClaw?** OpenClaw brings its own agent and Gateway, on any model provider, with many more chat apps, Linux, Windows and phone apps. Angelia runs the CLI you already use (Claude Code, Codex, Grok Build or pi) on macOS, on WhatsApp and Telegram, with one session and one folder per chat. [The comparison](https://useangelia.com/alternatives/) also covers Hermes Agent and Claude Code Remote Control.

**Is it safe?** Only paired chats reach the agent, and a command the profile may not run on its own waits for an owner's yes in the chat. Every profile is denied your credentials, Angelia's secrets and the other profiles' folders, but a deny binds the file tools, not every program: where other people can write, keep the shell asking or turn on the sandbox. Releases are signed, and there is no Angelia server ([Security model](https://useangelia.com/docs/security/)).

## Docs

- [README](https://raw.githubusercontent.com/korengast/angelia/v0.3.24/README.md): what Angelia is, install, quick start, chat commands, security in one minute, backends, FAQ
- [Reference](https://useangelia.com/docs/reference/): features in detail, capabilities per profile, setting things up by hand, the instance folder, every file Angelia keeps
- [Security model](https://useangelia.com/docs/security/): who can reach and command the agent, tokens, secrets, the sandbox, what leaves the machine
- [Docs on the site](https://useangelia.com/docs/): the reference, security model, runbook and decisions as web pages, built from the repository's main branch; each page's Markdown is at its URL plus `index.md`

## Pages

- [Claude Code on WhatsApp and Telegram: sessions, approvals](https://useangelia.com/claude-code/): what Angelia does for Claude Code, setup, approvals, voice notes, files, limits
- [Angelia for Codex: setup, sandbox, approvals and limits](https://useangelia.com/codex/): Codex's own OS sandbox with the profile's rules, approvals for more access, setup, test results, limits
- [Angelia for Grok Build: setup, approvals and limits](https://useangelia.com/grok/): trusting the folder, Grok Build's permission modes, approvals from the chat from 0.3.23, no sandbox, test results, limits
- [Angelia for pi: setup, sandbox, approvals and limits](https://useangelia.com/pi/): picking a model with /model, the approval gate, the macOS sandbox for every command, test results, limits
- [Claude Code on WhatsApp](https://useangelia.com/whatsapp/): the second number, linking by QR, groups, what works, privacy, limits
- [Claude Code Telegram bot](https://useangelia.com/telegram/): the bot, groups and topics, what works, privacy, limits
- [Angelia vs OpenClaw, Hermes Agent and Remote Control](https://useangelia.com/alternatives/): whose agent runs, chat apps, sessions, and when another tool fits better

## Local API

- [Build on Angelia](https://useangelia.com/docs/api.md): tokens, a quick start, the stable routes, events, and the stability promise
- [OpenAPI 3.1 document](https://useangelia.com/openapi.json): every route, field, error and example answer. A running daemon serves its own copy at `GET /openapi.json` on the socket, with no token
- [Example clients](https://github.com/korengast/angelia/tree/v0.3.24/examples/api): tested against a real daemon; Python with the standard library only, Node with no packages, and curl

## Optional

- [Claude Code on WhatsApp and Telegram, four ways compared](https://useangelia.com/guides/claude-code-whatsapp-telegram/)
- [How to control Claude Code from your phone](https://useangelia.com/guides/claude-code-from-phone/)
- [How to run Claude Code 24/7 on your own machine](https://useangelia.com/guides/claude-code-24-7/)
- [Claude Code notifications and approvals on your phone](https://useangelia.com/guides/claude-code-phone-notifications/)
- [Claude Code permissions: settings.json allow, ask, deny](https://useangelia.com/tools/claude-code-permissions/): tick boxes into a `.claude/settings.json` permissions block (allow, ask, deny, defaultMode)
- [Telegram bot token and chat id checker](https://useangelia.com/tools/telegram-bot-check/): getMe and getUpdates from the browser, to find the chat id a route needs
- [Runbook](https://useangelia.com/docs/runbook/): day-to-day commands, known failures and fixes, uninstalling
- [Decisions](https://useangelia.com/docs/decisions/): why it is built this way
- [Everything above in one file](https://useangelia.com/llms-full.txt)