🛡️ WRAP NEBULA

The AI agent kernel you can actually verify.

Local-first. Zero-trust. Auditable by design.

---

Important

Every AI coding agent sends your code to the cloud. No sandbox. No audit trail. No cryptographic guarantees. WRAP NEBULA does the opposite. Your code never leaves your machine.

---

🚀 What is WRAP NEBULA?

WRAP NEBULA is a local-first AI agent kernel that runs entirely on your machine. It provides a secure, auditable, and sandboxed execution environment for AI agents — with a Rust-powered policy governor, V8 isolate sandboxes, and Ed25519-signed audit trails.

flowchart LR
    subgraph INPUT["📥 Input Layer"]
        A[CLI] --> SAN
        B[Telegram Bot] --> SAN
        C[VS Code Extension] --> SAN
    end

    subgraph SECURITY["🔒 Security Layer"]
        SAN[Sanitizer<br/>PII Redaction + Injection Block] --> GOV
        GOV[Rust Governor<br/>Policy Enforcement] --> SOUL
    end

    subgraph BRAIN["🧠 Agent Layer"]
        SOUL[SOUL.md<br/>Agent Personality] --> LLM
        LLM[LLM Engine<br/>Ollama · Claude · GPT-4] --> SKILL
        SKILL[Skills<br/>V8 Sandboxed Executors] --> MEM
        MEM[Memory<br/>SQLite · Local Only]
    end

    subgraph OUTPUT["📤 Output Layer"]
        MEM --> SIGN
        SIGN[Ed25519 Signing<br/>Audit Trail] --> RESP
        RESP[Response]
    end

    style INPUT fill:#1a1a2e,stroke:#e94560,color:#fff
    style SECURITY fill:#16213e,stroke:#0f3460,color:#fff
    style BRAIN fill:#0f3460,stroke:#533483,color:#fff
    style OUTPUT fill:#1a1a2e,stroke:#e94560,color:#fff

Loading

Every message flows through this layered pipeline. Compromising one layer does not compromise the others.

---

⚔️ Why WRAP NEBULA?

Feature	Kilo	Cline	Cursor	WRAP NEBULA
Sandboxed Execution	❌	❌	❌	✅ V8 Isolate
Audit Trail	❌	❌	❌	✅ Ed25519 Signed
PII Redaction	❌	❌	❌	✅ Automatic
Local-First	partial	partial	❌	✅ Default
Zero Cloud Dependency	❌	❌	❌	✅ Total
Free Forever	❌	❌	❌	✅ MIT
Telegram Interface	❌	❌	❌	✅ Built-in
VS Code Extension	✅	✅	✅	✅ Included
Multi-LLM Support	partial	partial	❌	✅ Ollama/Claude/GPT-4
Rust Policy Engine	❌	❌	❌	✅ Governor

---

🏗️ Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        WRAP NEBULA                              │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐                      │
│  │   CLI    │  │ Telegram │  │ VS Code  │    INPUT SURFACES    │
│  └────┬─────┘  └────┬─────┘  └────┬─────┘                      │
│       │              │              │                            │
│       └──────────────┼──────────────┘                            │
│                      ▼                                          │
│  ┌──────────────────────────────────┐                           │
│  │         SANITIZER                │  ← PII redaction          │
│  │    injection blocking            │  ← prompt injection guard │
│  └──────────────┬───────────────────┘                           │
│                 ▼                                                │
│  ┌──────────────────────────────────┐                           │
│  │       RUST GOVERNOR              │  ← separate process       │
│  │    policy enforcement engine     │  ← survives agent crash   │
│  └──────────────┬───────────────────┘                           │
│                 ▼                                                │
│  ┌──────────────────────────────────┐                           │
│  │         AGENT CORE               │                           │
│  │  ┌─────────┐  ┌──────────────┐  │                           │
│  │  │ SOUL.md │→→│     LLM      │  │  ← Ollama / Claude / GPT  │
│  │  └─────────┘  └──────┬───────┘  │                           │
│  │                      ▼          │                           │
│  │  ┌─────────────────────────┐    │                           │
│  │  │    V8 SANDBOX SKILLS    │    │  ← 14 sandboxed executors │
│  │  │  web · code · file · …  │    │                           │
│  │  └─────────────────────────┘    │                           │
│  │                      ▼          │                           │
│  │         ┌────────────────┐      │                           │
│  │         │  SQLite Memory │      │  ← local only, encrypted  │
│  │         └────────────────┘      │                           │
│  └──────────────┬───────────────────┘                           │
│                 ▼                                                │
│  ┌──────────────────────────────────┐                           │
│  │      AUDIT & RESPONSE            │  ← Ed25519 signed         │
│  └──────────────────────────────────┘                           │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

---

🔥 Highlights

• 🏠 Local-First Gateway — your code, your machine, your rules. Zero cloud dependency by default.
• 🔒 Rust Governor — a separate Rust process enforces policies. Even if the JS agent is compromised, the governor holds.
• 🧪 V8 Isolate Sandboxing — every skill runs in an isolated V8 context. No filesystem, no network, unless explicitly granted.
• ✍️ Ed25519 Audit Trail — every agent response is cryptographically signed. Full chain of custody.
• 🔐 Automatic PII Redaction — sensitive data is stripped before it ever reaches the LLM.
• 🤖 Multi-LLM Support — Ollama (local), Claude, GPT-4. Swap models without changing code.
• 📱 Telegram Bot — talk to your agent from anywhere. Fully encrypted.
• 💻 VS Code Extension — native IDE integration. Inline suggestions, code actions, and chat.
• 🖥️ War Room Dashboard — web UI for monitoring sessions, audit logs, and system health.
• 🧠 SOUL.md — define your agent's personality in plain markdown. No config hell.
• 📦 14 Sandbox Skills — web search, code execution, file ops, system info, memory, and more.
• 🔑 One-Line Install — curl | bash and you're running.

---

🛠️ Skills

14 sandboxed executors — each runs in a V8 isolate with no filesystem or network access unless explicitly granted:

Skill	Description	Access
🔍 web.search	DuckDuckGo scraping, no API key	Network (read-only)
💻 code.execute	Sandboxed Python / JS / TS	None (pure compute)
📂 file.read	Read workspace files	FS (workspace-scoped)
📝 file.write	Write workspace files	FS (workspace-scoped)
🖥️ system.info	CPU, memory, disk stats	System (read-only)
🧠 memory.search	Semantic search over SQLite	DB (read-only)
🧠 memory.store	Store new memories	DB (write)
🌐 web.fetch	Fetch and parse URLs	Network (read-only)
📊 data.parse	Parse JSON/CSV/XML	None (pure compute)
🔐 crypto.hash	Hash and sign data	None (pure compute)
📅 time.now	Get current time/timezone	None (pure compute)
🧮 math.calc	Evaluate expressions	None (pure compute)
📧 email.read	Read inbox (IMAP)	Network (IMAP)
🗄️ db.query	Query local SQLite	DB (read-only)

---

📁 Project Structure

Wrap/
├── 📂 apps/
│   ├── 📂 vscode/              # VS Code extension
│   │   ├── src/                # Extension source
│   │   └── package.json
│   └── 📂 war-room/            # Web dashboard
│       ├── pages/              # Dashboard pages
│       └── components/
│
├── 📂 crates/
│   └── 📂 governor/            # 🔒 Rust policy engine
│       ├── src/                # Governor source
│       └── Cargo.toml
│
├── 📂 packages/
│   └── 📂 core/                # 🧠 Agent kernel
│       ├── src/
│       │   ├── agent/          # Agent loop & orchestration
│       │   ├── skills/         # Skill loader & definitions
│       │   ├── memory/         # SQLite memory layer
│       │   ├── audit/          # Ed25519 signing
│       │   └── sanitizer/      # PII redaction
│       └── package.json
│
├── 📂 skills/
│   └── 📂 default/             # Built-in skill definitions
│
├── 📂 policy/                  # Governance policy files
├── 📂 scripts/                 # Install & utility scripts
├── 📂 docs/                    # Documentation
├── 📂 tests/                   # Integration tests
│
├── 🔧 install.sh               # One-line installer
├── 📋 AUDIT.md                 # Audit trail documentation
├── 🔒 SECURITY.md              # Security policy
├── 🤝 CONTRIBUTING.md          # Contribution guidelines
└── 📄 LICENSE                  # MIT

---

🚀 Quick Start

One-Line Install

curl -fsSL https://raw.githubusercontent.com/Vitalcheffe/Wrap/main/install.sh | bash

Manual Setup

# Clone the repo
git clone https://github.com/Vitalcheffe/Wrap.git
cd Wrap

# Install dependencies
npm install

# (Optional) Build the Rust Governor
cd crates/governor && cargo build --release && cd ../..

# Authenticate with your LLM provider
nebula auth login anthropic

# Start the agent
nebula start

Prerequisites

Requirement	Version	Required?
Node.js	18+	✅
npm	9+	✅
Rust	1.70+	Optional (Governor)
Ollama	Latest	For local LLM

---

🔒 Security Model

Note

WRAP NEBULA's security is defense in depth. Every layer is independent.

Layer	Technology	What It Does
Sandbox	V8 Isolates	Each skill runs in complete isolation — no filesystem, no network, no shared memory
Governor	Rust (separate process)	Policy enforcement that survives agent crashes. Written in Rust, not JavaScript
Audit	Ed25519	Every response is cryptographically signed. Full chain of custody
PII Shield	Automatic	Sensitive data (emails, phones, keys, tokens) stripped before reaching the LLM
Local-First	SQLite + local filesystem	No data leaves your machine unless you explicitly configure a cloud LLM

---

🔌 Connection Modes

Mode	Use Case	Setup
💻 CLI	Direct terminal usage	nebula
🔌 VS Code	IDE-native experience	Install from apps/vscode/
📱 Telegram	Remote agent control	Connect your bot token
🖥️ War Room	Web monitoring dashboard	http://localhost:3000

---

🤝 Contributing

Contributions are what make the open-source community such an amazing place to learn, inspire, and create.

1. Fork the Project
2. Create your Feature Branch

   git checkout -b feature/AmazingFeature

3. Commit your Changes

   git commit -m 'feat: add AmazingFeature'

4. Push to the Branch

   git push origin feature/AmazingFeature

5. Open a Pull Request

See CONTRIBUTING.md for detailed guidelines, code style, and skill development docs.

---

📊 Stats

---

📄 License

Distributed under the MIT License. See LICENSE for more information. Free forever. No paywalls, no premium tiers, no "Contact Sales."

---

Made with ❤️, 🦀, and 🛡️ by Amine Harch el Korane

The AI agent you can actually trust.