# ⚑ 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 in Closed Alpha** β€” The "Vanexa AI" app is live on the Play Store, but the **Vanexa Agent** feature is currently in stealth development. This specific module is temporarily hidden from the public build as we finalize our sovereign neural routing. Early access to the Agent capabilities will be unlocked 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.**