Skip to content
villariasaPublic

About

Privacy-centric, local-first AI desktop operator and agentic task runner powered by Ollama and Electron.

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

Raphael — Local-First AI Desktop Operator

Electron React TypeScript Vite Tailwind Ollama

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.


Core Philosophy & Architecture

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:

  1. 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.
  2. 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.
  3. 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).
  4. Visual Cursor & Feedback Overlay — Non-intrusive transparent HUD overlay that displays cursor trajectories and visual indicators during automated tasks.
  5. Task Control & Audit Trails — Real-time progress display, step-by-step task tracking, instantaneous Pause / Resume / Abort capability, and persistent activity logging.

Technical Stack

  • 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)

Getting Started

Prerequisites

  • Node.js (v18 or higher)
  • Ollama installed and running locally with your desired model:
    ollama run llama3.1

Installation

# Clone the repository
git clone https://github.com/villariasa/Raphael.git
cd Raphael

# Install dependencies
npm install

AI Provider Setup

Raphael 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 .env

Supported 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.1

Development Mode

Run 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

Production Packaging

# Build desktop executable (Windows NSIS)
npm run dist:win

# Universal production build
npm run build

Safe Action Matrix

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

License

Private & Proprietary © Medy Villarias. All rights reserved.

About

Privacy-centric, local-first AI desktop operator and agentic task runner powered by Ollama and Electron.

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages