A privacy-centric, on-device AI desktop assistant and agentic automation operator.
Raphael plans and executes desktop workflows with strict human-in-the-loop permission gates, transparent visual overlays, and complete audit logging — with zero cloud telemetry.
Most autonomous AI agents execute shell commands and file operations blindly in the background or send your entire screen and keystrokes to remote servers. Raphael takes an enterprise-grade, local-first approach:
Free-API-First, Local Fallback — Tries whichever free-tier LLM APIs you've configured (Groq, Cerebras, DeepSeek, Gemini, and others) in order, and only falls back to a local model via Ollama if none are set up or reachable. No sensitive data leaves your machine when running fully local.
Safe Action Model (SAM) — Actions generated by the planner must strictly conform to a typed schema validated by
Zod. Unvalidated commands are rejected before execution.Granular Permission Gate — Every action is categorized by risk (
low,medium,high). Destructive or system-level actions trigger interactive modal approval (Allow Once,Always Allow,Deny).Visual Cursor & Feedback Overlay — Non-intrusive transparent HUD overlay that displays cursor trajectories and visual indicators during automated tasks.
Task Control & Audit Trails — Real-time progress display, step-by-step task tracking, instantaneous
Pause/Resume/Abortcapability, and persistent activity logging.
- Desktop Framework: Electron 32 + Node.js (with secure Context Isolation & sandboxed renderers)
- Frontend / UI: React 18, Vite 5, Tailwind CSS
- Type Safety & Contracts: TypeScript 5.5, Zod Runtime Validation
- Local AI Provider: Ollama Local API (
http://localhost:11434) - Packaging: electron-builder (NSIS installer for Windows, Linux AppImage/tar.gz)
- Node.js (v18 or higher)
- Ollama installed and running locally with your desired model:
ollama run llama3.1
# Clone the repository
git clone https://github.com/villariasa/Raphael.git
cd Raphael
# Install dependencies
npm installRaphael tries free-tier LLM APIs first, in priority order, and falls back to local Ollama if none are configured or reachable. Copy .env.example to .env and fill in whichever free keys you have — all are optional:
cp .env.example .envSupported providers (see .env.example for the sign-up link for each): Groq, Cerebras, DeepSeek, Google Gemini, SambaNova, Mistral AI, NVIDIA NIM, xAI (Grok), OpenRouter, Hugging Face, Z AI (Zhipu), and ModelScope. Full list: open-free-llm-api/awesome-freellm-apis.
No keys set? Raphael runs entirely offline against local Ollama, same as before — install it and pull a model:
ollama run llama3.1Run the dual-process dev environment (Vite renderer + TypeScript main watcher):
# In terminal 1: Start renderer
npm run dev:renderer
# In terminal 2: Build main process and launch Electron
npm run start# Build desktop executable (Windows NSIS)
npm run dist:win
# Universal production build
npm run build| Action Kind | Risk Level | Description |
|---|---|---|
read_system_info |
Low | Queries OS version, architecture, and shell environment |
list_installed_applications |
Low | Enumerates installed software packages |
read_file |
Low | Reads file content without mutation |
create_folder |
Medium | Creates new directories safely within user scopes |
create_file / modify_file |
Medium | Safe-path file generation and modification |
open_application |
Medium | Launches registered system applications |
execute_command |
High | Terminal command execution (explicit confirmation required) |
modify_path / modify_registry |
High | System environment & registry modifications |
delete_file |
High | File removal operations |
Private & Proprietary © Medy Villarias. All rights reserved.