# ⚑ Vanexa Agent **Your Sovereign AI β€” Controlled from Your Phone.** [![npm version](https://img.shields.io/npm/v/@vanexalabs-ai/vanexa-agent)](https://www.npmjs.com/package/@vanexalabs-ai/vanexa-agent) [![Downloads](https://img.shields.io/badge/Total_Downloads-14.6K%2B-blue)]() [![License: BUSL-1.1](https://img.shields.io/badge/License-BUSL--1.1-blue.svg)](LICENSE) [![Platform](https://img.shields.io/badge/Platform-macOS%20%7C%20Windows%20%7C%20Linux-brightgreen)]() > πŸ”’ **Vanexa Agent β€” not yet publicly released.** The "Vanexa AI" app is live on the Play Store, but the **Vanexa Agent** feature is disabled in the current public app build while we finalize sovereign neural routing. Early access will be enabled soon. Vanexa Agent is a **sovereign, mobile-first autonomous AI system** that turns your computer into an AI-powered workhorse β€” controlled entirely from an Android app. Give it a natural language instruction from your phone, and it will autonomously plan, code, execute terminal commands, manage files, search the web, build games, generate media, and much more β€” streaming real-time progress back to your phone.
--- ## πŸ“± Companion App Required Vanexa Agent is designed as a **headless daemon**. It runs silently on your computer and receives all commands, configurations, and approvals through the official Android companion app. **[πŸ“₯ Download "Vanexa AI" on Google Play Store](https://play.google.com/store/apps/details?id=com.vanexa.supercalculator)** The companion app provides: - πŸŽ›οΈ Full agent configuration (AI provider, model, API key, autonomy mode) - πŸ“‘ Real-time task monitoring with live streaming output - πŸ›‘οΈ Human-in-the-Loop approval for dangerous operations - πŸ”‘ BYOK (Bring Your Own Key) management for 9 AI providers - πŸ“‚ Workspace path scoping (control which directories the agent can access) - 🧠 Memory & privacy management (clear agent memory on-demand) - πŸ›‘ Kill switch β€” instantly abort any running task --- ## πŸš€ Quick Start (30 Seconds) Install globally via npm: ```bash npm install -g @vanexalabs-ai/vanexa-agent ``` After installation, pair with your phone: ```bash vanexa-agent pair ``` --- ## πŸ›οΈ Architecture Overview Vanexa operates on a **Sovereign Peer-to-Peer Architecture** β€” powered by WebRTC: ``` β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ πŸ“± ANDROID APP β”‚ ⚑ WebRTC DataChannel (P2P) β”‚ πŸ’» CLI DAEMON β”‚ β”‚ (Command Center) │◄═══════════════════════════════════►│ (Your Computer) β”‚ β”‚ β”‚ Direct Encrypted Tunnel β”‚ β”‚ β”‚ β€’ Task Input β”‚ No Server in the Middle β”‚ β€’ AgentLoop (Brain) β”‚ β”‚ β€’ Live Monitoring β”‚ β”‚ β€’ 64+ Tools (Hands) β”‚ β”‚ β€’ Config Sync β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ β€’ 4-Layer Sandbox β”‚ β”‚ β€’ Kill Switch β”‚ β”‚ ☁️ Signaling β”‚ β”‚ β€’ Cortex Memory β”‚ β”‚ β€’ Approval UI β”‚ β”‚ (5 sec only) β”‚ β”‚ β€’ 10 LLM Providers β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ ``` 1. **You type** a task on your phone (e.g., "Build me a portfolio website") 2. **A 5-second handshake** establishes a direct encrypted tunnel between your phone and computer β€” then the signaling server disconnects. **No middleman.** 3. **The AgentLoop** on your computer plans the task, calls your chosen LLM, and autonomously executes tools in a Plan β†’ Act β†’ Observe β†’ Reflect loop 4. **You monitor** every step in real-time on your phone, and approve or deny dangerous operations > πŸ’‘ **Zero-Server Data Path.** After the initial handshake, all communication flows directly between your phone and computer via an encrypted WebRTC DataChannel. No server ever sees your tasks, API keys, or data. --- ## πŸ”§ What Can It Do? The agent ships with **64+ native tools** across 10 domains, plus a self-evolving tool engine: | Domain | Capabilities | |--------|-------------| | **Terminal** | Execute commands, run background processes, maintain persistent shell sessions (stateful REPL) | | **File System** | Read, write, edit (surgical search/replace), multi-edit, search (regex grep), find (glob), list, move, delete | | **Code Intelligence** | Syntax verification, symbol listing, AST search, Ripgrep-powered code search, semantic codebase search | | **Git** | Full git operations with risk-mapped approval gates | | **Web** | Fetch URLs (with SSRF protection), DuckDuckGo + Google web search | | **Desktop Automation** | Browser automation (Puppeteer-like), desktop screenshots, clipboard read/write, UI vision inspection, open files/URLs | | **Media Generation** | Procedural SVG/audio generation, AI image/video generation (auto-routes to your provider's native API: Gemini Imagen, OpenAI DALLΒ·E, Qwen Wanx β€” with Pollinations.ai as free fallback), PDF text extraction, image OCR/vision | | **3D & Game Engines** | Blender 3D automation (socket bridge), Godot 4.x automation, HTML5 game builder (Three.js/Canvas 2D), 15+ game development tools (lore, quests, dialogue trees, shaders, VFX, audio, tilemaps, UI/HUD, economy balancing, and more) | | **Cognitive** | Task planning (TodoWrite), persistent memory, sub-agent orchestration (parallel worker swarm), deferred MCP tool discovery | | **System** | Archive creation (zip/tar), system spec checks, printer integration, adaptive tool forge (the agent can dynamically create and hot-reload its own new tools at runtime) | --- ## 🧠 Sovereign Memory System The agent maintains **four distinct memory layers**, all stored 100% locally on your machine: | Layer | Purpose | Persistence | |-------|---------|-------------| | **Sliding Window** | Current conversation context with asymmetric pruning | Per-session, saved to disk | | **Fact Store** | Explicit facts the agent deliberately memorizes about you and your projects | Permanent (JSON) | | **Cortex Vector DB** | Semantic long-term memory β€” the agent learns from past mistakes and recalls solutions via cosine similarity search | Permanent (SQLite) | | **Tool Forge** | Self-created tools that the agent writes and hot-reloads at runtime | Permanent (JS files) | The Cortex system runs entirely on-device using a local neural embedding engine β€” no cloud API calls required. --- ## πŸ”‘ BYOK (Bring Your Own Key) Vanexa Agent uses **your own API keys** β€” no middleman, no data leaves your machine. Just plug in your key and go. | Provider | Available Models | Vision | |----------|-----------------|:------:| | DeepSeek | `deepseek-v4-flash`, `deepseek-v4-pro` | ❌ | | OpenAI | `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna`, `gpt-5.4-mini` | βœ… | | Anthropic | `claude-fable-5`, `claude-opus-4.8`, `claude-sonnet-5`, `claude-haiku-4.5` | βœ… | | Gemini | `gemini-3.5-flash`, `gemini-3.1-pro`, `gemini-3.1-flash-lite` | βœ… | | Qwen | `qwen3.7-max`, `qwen3.7-plus`, `qwen3.6-flash` | ❌ | | Moonshot (Kimi) | `kimi-k3`, `kimi-k2.7-code`, `kimi-k2.6` | ❌ | | xAI (Grok) | `grok-4.5`, `grok-latest` | ❌ | | Alibaba (DashScope) | `qwen3.7-max`, `qwen3.7-plus`, `deepseek-v4-flash`, `kimi-k2.7-code`, and more | ❌ | | Ollama | Any locally installed model | ❌ | > Models listed are the **code defaults**. The companion app lets you select from a curated list of available models per provider, which may include newer models not listed here. Configure your key in the Vanexa phone app under **Agent β†’ Settings β†’ API Configuration**. --- ## πŸ›‘οΈ Security - **4-Layer Sandbox**: Tool availability checks β†’ Path scoping β†’ Command risk classification β†’ SSRF protection - **3 Autonomy Modes**: Passive (ask everything) β†’ Supervised (auto-safe, ask-dangerous) β†’ Autonomous (full auto) - **Self-Preservation**: The agent cannot read, modify, or delete its own source code - **Workspace Scoping**: The phone app controls exactly which directories the agent can access - **Proprietary Source**: Distributed as compiled V8 Bytecode (`.jsc`), not readable JavaScript --- ## πŸ–₯️ CLI Commands ```bash vanexa-agent pair # Pair with your phone vanexa-agent start # Start the daemon (listens for phone commands) vanexa-agent stop # Stop the daemon vanexa-agent restart # Restart the daemon vanexa-agent status # Check if daemon is running vanexa-agent config # Configure API provider interactively vanexa-agent chat # Start interactive chat mode (no phone needed) vanexa-agent run # Run a single task from CLI vanexa-agent exec # Quick execute a terminal command vanexa-agent update # Update to the latest version ``` --- ## πŸ”§ Manual Installation (Advanced) If you already have **Node.js v24+** installed: ```bash npm install -g @vanexalabs-ai/vanexa-agent vanexa-agent pair ``` --- ## πŸ› οΈ Troubleshooting ### `npx: command not found` Node.js is not installed. Install Node.js manually from [nodejs.org](https://nodejs.org). ### `EACCES: permission denied` On macOS/Linux, fix npm permissions: ```bash sudo npm install -g @vanexalabs-ai/vanexa-agent ``` Or use the recommended approach: ```bash mkdir ~/.npm-global npm config set prefix '~/.npm-global' echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc source ~/.bashrc npm install -g @vanexalabs-ai/vanexa-agent ``` ### Windows: `running scripts is disabled` Run PowerShell as Administrator and execute: ```powershell Set-ExecutionPolicy RemoteSigned -Scope CurrentUser ``` --- ## πŸ—‘οΈ Uninstall ```bash npm uninstall -g @vanexalabs-ai/vanexa-agent ``` --- ## πŸ›‘οΈ Security & Privacy Vanexa Agent is built with a **sovereignty-first** security model: - **True Peer-to-Peer.** Your phone and computer communicate directly via an encrypted WebRTC DataChannel. No server sits in the data path β€” your commands, results, and credentials never transit through any third party. - **API keys never leave your machine.** Your LLM API keys are stored locally in `~/.vanexa/config.json` and are sent directly from your computer to your chosen AI provider. - **5-Second Signaling, Then Gone.** The cloud signaling server only facilitates the initial WebRTC handshake (~5 seconds). It sees zero task content β€” only connection metadata (ICE/SDP). After the handshake, it disconnects. - **BYOK (Bring Your Own Key).** Vanexa does not provision, manage, or have access to your API keys. You control your own billing with your AI provider. - **Human-in-the-Loop.** In Mode B (default), the agent requests explicit approval from your phone before executing any potentially destructive operation (e.g., `rm`, `sudo`, system-level changes). - **V8 Bytecode.** The compiled bytecode (`bundle.jsc`) is a standard commercial IP protection measure. The full source logic is auditable via the bundled `bundle.cjs` fallback. > If you have security concerns or wish to report a vulnerability, please contact: **vanexa.help@gmail.com** or **ikbalf500445@gmail.com** --- ## πŸ“„ License Business Source License 1.1 (BUSL-1.1) Β© Ikbal Fadilah ---
**Your computer. Your keys. Your rules.**