Angelia · Updated 27 October 2026

Angelia for pi: setup, sandbox, approvals and limits

Angelia connects the pi coding agent on your Mac to WhatsApp and Telegram. Each chat gets its own pi session, in its own folder, on the model you pick. pi has no permission prompt and no sandbox of its own, so Angelia adds both: a gate that asks in the chat, and macOS's sandbox around every shell command. Angelia runs no model of its own: pi does the work, under the logins you gave it.

What Angelia does for pi

• One session per chat. Each chat is routed to a profile: a folder with its own instructions and memory. Angelia keeps one pi --mode rpc process per chat, and the session comes back after a restart. /new in one chat never touches another.
• Approvals pi does not have. Angelia loads a gate extension into pi. A command or a file write that the profile's mode does not allow on its own comes to the chat and waits for an owner's yes.
• A sandbox pi does not have. Every shell command runs inside macOS's sandbox (sandbox-exec), made from the profile's deny rules. The kernel refuses a denied path however the command spells it, for every program the command starts.
• Your instructions and skills. pi reads the profile's CLAUDE.md (or an AGENTS.md, when the folder has one). The skills the profile was given are passed to pi one by one; pi does not read Claude's skills folder.

What you need

• A Mac with Node 22.23.4+, 24.22.1+ or 26.12.1+ and git.
• pi 0.80.4 or newer. Check with pi --version.
• A working login for at least one model provider. pi signs in per provider: run pi in a terminal and use its own /login. A Claude subscription used through pi draws on extra usage, and fails without it.
• A chat app on your phone. For Telegram, a bot token from @BotFather (more). For WhatsApp, a second, established number, not your personal one (why).
• Optional: brew install openai-whisper ffmpeg for voice notes.

Set it up

curl -fsSL https://useangelia.com/install | sh
angelia service install

The first line checks the release's signature, installs Angelia and starts a setup wizard (read the script). Pick Quick or Advanced, then Telegram, WhatsApp or both. Pick pi as the CLI, then send the bot (or the second number) a message from your phone to pair the chat. The second line keeps Angelia running.

Already running Angelia with another CLI? An owner sends /backend pi in one of the profile's chats. Angelia edits the routing table, ~/.angelia/workspace/routing.yaml, with a backup, compiles the profile for pi and starts a fresh session.

Pick a model

pi's own default model may be from a provider with no login on this Mac. So after the switch, Angelia says to pick one. /model lists the models pi has a login for, as provider/model. Then set one for this session:

/model xai/grok-4.7

To keep a model for the profile, set model: on it in routing.yaml, then angelia accept and /restart.

What works from the chat

Approvals

The question comes to the chat as it does for Claude Code, and an owner answers yes <id> or no <id>. No answer in ten minutes means no. What asks depends on the profile's permission_mode:

• default: every shell command and every file write asks.
• acceptEdits: file writes inside the profile's folders run. Commands ask, except a short read-only list (ls, cat, head, wc, echo and the like) on paths inside the profile's folders.
• bypassPermissions: nothing asks. Commands and file writes then write only in the profile's folders, its cache folder and temp.
• plan: pi gets only its read, grep, find and ls tools.

pi's file tools read without asking, unless a deny rule covers the path. A command an owner approved may write outside the profile's folders; the deny rules still hold. Sending a file back in default mode takes two yes answers: one to write the file, one for the command that sends it.

What the sandbox does

• A path under a deny rule cannot be read or written: your credentials, Angelia's own files, the other profiles' folders.
• The network is open to commands.
• The ssh agent is not passed on. Tools that keep their login under the deny rules (gh, ssh keys, cloud CLIs) fail inside, and the agent is told so.
• Package caches (npm, pip, uv) go to the profile's own cache folder.
• No command runs longer than 600 seconds.
• sandbox: false on the profile runs commands without it. The deny rules then hold for pi's file tools only.

Voice notes, photos and files

A photo or document you send lands in the profile's .inbox/ folder, up to 20 MB, and pi gets a [file: path] line. A voice note arrives as [voice note: path], and the agent runs angelia transcribe <path>. pi sends files back with angelia send-media. Every path is checked first: never a credential location, never another profile's folder.

Chat commands

/new, /stop, /status, /resume, /model, /effort, /backend, /restart and the others /help lists are answered by Angelia, without spending a token. /compact goes to pi's own compact command. When a provider hits a usage limit, the chat says to pick another model with /model. Long answers are split as for every CLI.

Tested

On 2026-10-27, with Angelia 0.3.22 and pi 0.86.1 on macOS, in a WhatsApp group routed to one profile in permission_mode: default. The model was xai/grok-4.7, picked with /model in the chat.

• The first answer came in about 16 seconds. About 14 seconds of that was pi starting.
• A long answer arrived in 2 messages, in order.
• Approvals worked: yes <id> ran the command, and no <id> declined it.
• A file sent back with angelia send-media arrived in the chat.
• /status, /new and /stop work.

pi on Telegram is not tested yet. Voice notes are tested with Claude Code only.

Limits

• macOS only. The sandbox is macOS's own; without it, every command is refused. The Mac must be on and awake: while it sleeps, nothing answers.
• No MCP servers on pi.
• The sandbox is a guard rail, not a wall. A command can still ask a program outside it to act (launchd, Apple Events, open). That is why only bypassPermissions runs commands without asking, and a group open to every member is refused on a bypass pi profile.
• Your own pi extensions still load, and pi's shellCommandPrefix setting runs outside the sandbox. angelia compile warns when one is set.
• Prompt injection is not solved. A web page or a forwarded message can still talk the agent into what its mode allows. Read the security model before you give the bot to anyone but yourself.
• It is a young project (v0.3), maintained by one person.

curl -fsSL https://useangelia.com/install | sh