Deploy Main Space

README.md

@@ -0,0 +1,607 @@
+---
+title: NACC - Network Agentic Command Control
+emoji: 🚀
+colorFrom: blue
+colorTo: purple
+sdk: gradio
+app_file: app.py
+pinned: false
+license: mit
+short_description: Autonomous AI Agent Orchestrator for Multi-Node Control
+
+tags:
+- mcp-in-action-track-enterprise
+- mcp-in-action-track-consumer
+- mcp-in-action-track-creative
+- building-mcp-track-enterprise
+- building-mcp-track-consumer
+- building-mcp-track-creative
+---
+
+# 🚀 NACC Orchestrator: Network Agentic Command Control
+
+> **Turn your entire network into a single, intelligent entity.**
+
+NACC is an **Autonomous AI Agent Application** that orchestrates multiple computers as a unified intelligent system using the **Model Context Protocol (MCP)**. It showcases autonomous reasoning, planning, and execution across distributed nodes—controlling Mac, Linux, and VM environments through natural language. Whether managing enterprise infrastructure, home labs, or creative workflows, NACC demonstrates the true power of MCP-enabled AI agents.
+
+---
+
+### 🎥 [Watch the Video Demo](LINK_TO_YOUR_VIDEO_HERE)
+### 🐦 [See it on X / LinkedIn](LINK_TO_YOUR_SOCIAL_POST_HERE)
+
+---
+
+## 🏆 Hackathon Tracks
+
+### 🎯 Primary: Track 2 - MCP in Action
+
+NACC is a **complete AI agent application** that demonstrates autonomous reasoning, planning, and execution:
+
+*   **🏢 Enterprise Applications** (`mcp-in-action-track-enterprise`): Multi-node orchestration for distributed infrastructure management, automated deployments, and coordinated system administration
+*   **👤 Consumer Applications** (`mcp-in-action-track-consumer`): User-friendly natural language interface for home labs, personal workflows, and everyday task automation
+*   **🎨 Creative Applications** (`mcp-in-action-track-creative`): Innovative hub-and-spoke architecture enabling unprecedented cross-machine AI coordination and distributed creative workflows
+
+**What makes NACC an AI Agent Application:**
+- **Autonomous Reasoning**: AI interprets complex multi-step requests and plans execution across nodes
+- **Dynamic Planning**: Intelligently routes commands based on node capabilities and current context
+- **Autonomous Execution**: Executes coordinated actions across multiple machines without manual intervention
+
+### 🔧 Secondary: Track 1 - Building MCP
+
+NACC also functions as an **MCP Server** extending LLM capabilities:
+
+*   Exposes powerful tools for distributed file operations, shell execution, and cross-node synchronization
+*   Integrates with Claude Desktop and any MCP-compatible client
+*   Built entirely on MCP protocol for standardized AI-to-system communication
+
+This project was built **from the ground up** using the Model Context Protocol, showcasing true innovation in distributed AI orchestration.
+
+---
+
+## �📑 Table of Contents
+
+- [Hackathon Categories](#-hackathon-categories)
+- [Architecture](#-architecture)
+- [Key Features](#-key-features)
+- [Why Blaxel](#-why-blaxel-powers-nacc)
+- [How It Works](#-how-it-works)
+- [Installation & Setup](#%EF%B8%8F-installation--setup)
+- [Configuration](#%EF%B8%8F-configuration)
+- [Usage Guide](#-usage-guide)
+- [Example Workflows](#-example-workflows)
+- [Tech Stack](#%EF%B8%8F-tech-stack)
+- [Platform Compatibility](#-platform-compatibility)
+- [Troubleshooting](#-troubleshooting)
+- [FAQ](#-faq)
+- [Team Members](#-team-members)
+
+---
+
+## 🧠 Architecture
+
+NACC uses a **Hub-and-Spoke** architecture where a central Orchestrator manages multiple distributed Nodes.
+
+```mermaid
+graph TD
+    User["👤 User"] -->|Natural Language| UI["💻 NACC Web UI / Claude Desktop"]
+    UI -->|JSON-RPC| Orch["🧠 Orchestrator - The Brain"]
+    
+    subgraph Local Network
+        Orch -->|HTTP/MCP| Node1["🖥️ Node 1 - MacBook"]
+        Orch -->|HTTP/MCP| Node2["🐧 Node 2 - Kali VM"]
+        Orch -->|HTTP/MCP| Node3["☁️ Node 3 - Ubuntu Server"]
+    end
+    
+    Node1 -->|Execute| FS1["📂 Filesystem / Shell"]
+    Node2 -->|Execute| FS2["📂 Filesystem / Shell"]
+    Node3 -->|Execute| FS3["📂 Filesystem / Shell"]
+```
+
+## 🌟 Key Features
+
+*   **🗣️ Natural Language Control**: "Switch to Kali and scan the network" -> Executed instantly.
+*   **🔌 MCP Native**: Built from scratch on the Model Context Protocol for standardized communication.
+*   **📂 Dynamic File Operations**: Create, read, edit, and delete files across any connected node using natural language.
+*   **🔄 Context-Aware Navigation**: The system remembers which node you're on and your current directory.
+*   **🛡️ Secure & Private**: Designed for **local networks**. Your data stays within your LAN.
+*   **🎨 Professional UI**: Modern, dark-themed interface built with Gradio 6.0.
+*   **⚡ Powered by Blaxel**: Lightning-fast serverless AI inference with zero configuration.
+*   **🤖 Multi-Backend Support**: Works with OpenAI, Anthropic, Gemini, Mistral, Llama, or local LLMs via Ollama.
+
+---
+
+## ⚡ Why Blaxel Powers NACC
+
+NACC uses **[Blaxel](https://blaxel.com)** as its default AI backend, and for good reason:
+
+### 🚀 Flawless Performance
+*   **Zero Configuration**: Works out of the box - no API keys needed for testing
+*   **Lightning Fast**: Sub-second response times for command execution
+*   **Always Available**: 99.9% uptime serverless infrastructure
+*   **Cost Effective**: Pay only for what you use, perfect for demos and development
+
+### 🎯 Perfect for NACC
+Blaxel's serverless architecture aligns perfectly with NACC's distributed nature:
+*   No cold starts when orchestrating multiple nodes
+*   Handles concurrent requests across nodes seamlessly
+*   Automatically scales with your network growth
+
+### 💡 Acknowledgment
+A huge thank you to the **Blaxel team** for building such a robust platform! Their commitment to making AI accessible and performant has been instrumental in bringing NACC to life. *We'd love to collaborate further - internship opportunities welcome!* 😊
+
+While NACC supports multiple backends (OpenAI, Anthropic, Gemini, Ollama), Blaxel remains our recommended choice for its perfect balance of speed, reliability, and ease of use.
+
+---
+
+## 🔍 How It Works
+
+NACC operates through a sophisticated request flow that bridges natural language and system commands:
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant UI as NACC UI
+    participant LLM as AI Backend
+    participant Orch as Orchestrator
+    participant Node as Target Node
+    
+    User->>UI: "Create file test.txt on kali-vm"
+    UI->>Orch: Send query with context
+    Orch->>LLM: Parse intent + context
+    LLM->>Orch: {tool: "write_file", node: "kali-vm", path: "test.txt"}
+    Orch->>Node: HTTP POST /tools/write-file
+    Node->>Node: Execute on filesystem
+    Node->>Orch: {success: true, path: "/home/user/test.txt"}
+    Orch->>UI: Format response
+    UI->>User: "✅ File created on kali-vm"
+```
+
+### Core Components
+
+1.  **UI Layer** (`nacc_ui/`): Gradio-based chat interface with context management
+2.  **Orchestrator** (`nacc_orchestrator/`): Central brain that routes requests and manages node registry
+3.  **Node Agents** (`nacc_node/`): Lightweight servers exposing MCP tools for file/shell operations
+4.  **LLM Backend**: Interprets natural language and selects appropriate tools
+
+---
+
+## 🛠️ Installation & Setup
+
+### Prerequisites
+*   **Python 3.10+** installed on all machines.
+*   **Network**: All machines (Orchestrator and Nodes) must be on the **same local network** (LAN).
+*   **Git**: For cloning the repository.
+
+### 🎮 Demo Guide
+
+NACC can be demonstrated in two powerful ways. Choose the one that fits your environment:
+
+### ☁️ Option 1: Cloud Demo (Hugging Face Spaces)
+**Perfect for:** Judges, quick testing, zero setup.
+
+1.  **Open the Space**: Go to the NACC Space.
+2.  **Auto-Connect**: You will see **`✅ Online: Local Node (Demo)`** immediately. This is a real node running *inside* the Space container.
+3.  **Try Commands**:
+    *   "List files in current directory"
+    *   "Create a file named hello.txt with content 'Hello from HF Space!'"
+4.  **Multi-Node Magic** (Optional):
+    *   If you deployed the **VM Node Space**, connect to it:
+    *   *"Connect to node at https://mcp-1st-birthday-virtual-machine.hf.space and name it Remote-VM"*
+    *   Now you can switch between nodes: *"Switch to Remote-VM and list files"*
+
+### 🏠 Option 2: Real-World Demo (Local Network)
+**Perfect for:** Full power, controlling physical devices, home labs.
+
+1.  **Run Orchestrator**: `python -m src.nacc_orchestrator.cli serve` on your main computer.
+2.  **Run Nodes**: `python -m src.nacc_node.cli serve` on your other laptops, Raspberry Pis, or VMs.
+3.  **Connect**:
+    *   *"Connect to node at 192.168.1.15 and name it MacBook-Pro"*
+    *   *"Connect to node at 192.168.1.20 and name it Kali-Linux"*
+4.  **Orchestrate**:
+    *   *"Check CPU usage on all nodes"*
+    *   *"Sync the 'project' folder from MacBook-Pro to Kali-Linux"*
+
+---
+
+## 🚀 Quick Start (Local) (For Judges)
+
+```bash
+# Clone the repository
+git clone https://github.com/Vasanthadithya-mundrathi/NACC.git
+cd NACC
+
+# Setup environment (Mac/Linux)
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+
+# Start the Orchestrator
+./start_nacc.sh
+```
+
+Open your browser to `http://localhost:7860` - You're ready!
+
+### Detailed Setup
+
+#### 1. Setting up the Orchestrator (The Brain)
+Run this on your main computer (e.g., MacBook, PC).
+
+1.  **Clone the Repository**
+    ```bash
+    git clone https://github.com/Vasanthadithya-mundrathi/NACC.git
+    cd NACC
+    ```
+
+2.  **Install Dependencies**
+    ```bash
+    python3 -m venv .venv
+    source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+    pip install -r requirements.txt
+    ```
+
+3.  **Make Scripts Executable** (Mac/Linux only)
+    ```bash
+    chmod +x start_nacc.sh
+    ```
+
+4.  **Start the Orchestrator**
+    ```bash
+    ./start_nacc.sh
+    ```
+    
+    The UI will be available at `http://localhost:7860`.
+
+#### 2. Setting up Nodes (The Agents)
+Run this on any other machine you want to control.
+
+> **💡 Recommendation**: We highly recommend installing NACC Nodes in a **Virtual Machine (VM)** (like Kali Linux or Ubuntu) to safely test the powerful command execution capabilities without affecting your main system.
+
+1.  **Install NACC** (Same steps as above: clone & install requirements).
+
+2.  **Start the Node**
+    Run the node agent, specifying a unique name and port:
+    ```bash
+    # On the Node machine (e.g., Kali VM)
+    python3 -m nacc_node.main --name "kali-vm" --host 0.0.0.0 --port 8001
+    ```
+    
+    *Note: `0.0.0.0` allows the node to accept connections from any IP on your local network. Note the IP address of this machine (e.g., `192.168.1.15`).*
+
+---
+
+## ⚙️ Configuration
+
+### API Keys & Backend Selection
+
+NACC supports multiple AI backends. You can configure them via:
+
+1.  **Environment Variables** (Recommended for production):
+    ```bash
+    export OPENAI_API_KEY="sk-..."
+    export ANTHROPIC_API_KEY="sk-ant-..."
+    export GEMINI_API_KEY="..."
+    export BLAXEL_API_KEY="..."
+    ```
+
+2.  **UI Settings**: Use the Settings tab in the NACC Web UI to enter keys and select your backend.
+
+3.  **Config Files**: Edit `configs/orchestrator-config.yml` for advanced configuration.
+
+### Supported Backends
+
+| Backend | Model | Notes |
+|---------|-------|-------|
+| **OpenAI** | GPT-4, GPT-4 Turbo | Best overall performance |
+| **Anthropic** | Claude 3.5 Sonnet | Excellent for complex reasoning |
+| **Google** | Gemini 1.5 Pro | Fast and cost-effective |
+| **Blaxel** | (Serverless) | Pre-configured for quick start |
+| **Ollama** | Llama 3, Mistral | Run locally (requires Docker) |
+
+### Custom Configuration
+
+Edit `configs/orchestrator-config.yml` to:
+*   Add static nodes (nodes that auto-connect on startup)
+*   Configure default timeouts
+*   Set audit log paths
+*   Customize allowed commands per node
+
+Example:
+```yaml
+nodes:
+  - node_id: "macbook-local"
+    transport: "local"
+    root_dir: "/Users/yourname"
+    tags: ["mac", "local"]
+    
+agent_backend:
+  provider: "openai"
+  model: "gpt-4-turbo"
+```
+
+---
+
+## 🚀 Usage Guide
+
+### Connecting a Node
+Once your Orchestrator and Node are running:
+
+1.  Open the NACC UI (`http://localhost:7860`).
+2.  In the Chat interface, type:
+    > "Connect to node at 192.168.1.15 on port 8001 and name it kali-vm"
+3.  The system will register the node. You can verify by asking:
+    > "List all connected nodes"
+
+### Controlling Nodes
+You can now switch contexts and control any node naturally.
+
+**Navigation & Exploration:**
+```
+"Switch to kali-vm"
+"Navigate to Documents folder"
+"List all files in this directory"
+"Go back to parent directory"
+```
+
+**File Operations:**
+```
+"Create a file named 'notes.txt' with content 'Meeting at 5 PM'"
+"Read the content of 'notes.txt'"
+"Delete 'notes.txt'"
+"Write 'Updated content' to existing.txt"
+```
+
+**Cross-Node Actions:**
+```
+"Switch to macbook-local"
+"Share test.txt from kali-vm to macbook-local"
+"Check system stats on all nodes"
+```
+
+### Using with MCP Clients (Claude Desktop)
+
+NACC acts as an MCP Server, meaning you can connect it to Claude Desktop or any MCP-compatible client!
+
+1.  **Configure Claude Desktop**:
+    Add this to your `claude_desktop_config.json` (usually in `~/AppData/Roaming/Claude/` on Windows or `~/Library/Application Support/Claude/` on Mac):
+    ```json
+    {
+      "mcpServers": {
+        "nacc": {
+          "command": "uv",
+          "args": [
+            "--directory",
+            "/absolute/path/to/NACC",
+            "run",
+            "nacc-orchestrator"
+          ]
+        }
+      }
+    }
+    ```
+
+2.  **Alternative (Python Direct)**:
+    ```json
+    {
+      "mcpServers": {
+        "nacc": {
+          "command": "python3",
+          "args": [
+            "-m",
+            "nacc_orchestrator.mcp_server"
+          ],
+          "env": {
+            "PYTHONPATH": "/absolute/path/to/NACC"
+          }
+        }
+      }
+    }
+    ```
+
+3.  **Restart Claude Desktop**. You can now ask Claude:
+    > "List files on my Kali VM"
+    > "Create a backup directory on my Ubuntu server"
+
+---
+
+## 💡 Example Workflows
+
+### Scenario 1: Basic File Operations (Local Node)
+
+**Goal**: Organize your files using AI.
+
+**Prompt**:
+> "Create a directory called 'test_data', write a file named 'notes.txt' inside it with the text 'Hello World', and then read it back to me."
+
+**What Happens**:
+1.  Intent Parser identifies 3 steps (Create Dir, Write File, Read File).
+2.  Orchestrator executes them sequentially on the local node.
+3.  Result: You see the file content "Hello World" in the chat.
+
+### Scenario 2: Network Security Scan (Kali Node)
+
+*Requires a connected Kali Linux node.*
+
+**Goal**: Scan a target IP for vulnerabilities.
+
+**Prompt**:
+> "Switch to the Kali node. Run an nmap scan on 192.168.1.50 to find open ports. If you find port 80, try to curl the homepage."
+
+**What Happens**:
+1.  Router routes the request to the `kali-vm` node.
+2.  Agent executes `nmap -F 192.168.1.50`.
+3.  Logic: If output contains "80/tcp open", the Agent executes `curl http://192.168.1.50`.
+4.  Result: The AI summarizes the open ports and the web page content.
+
+### Scenario 3: Multi-Node Workflow
+
+*Requires multiple connected nodes.*
+
+**Goal**: Distributed task execution.
+
+**Prompt**:
+> "Check the CPU usage on the MacBook node, and if it's below 50%, tell the Cloud node to start the backup process."
+
+**What Happens**:
+1.  Orchestrator queries MacBook node for system stats.
+2.  Orchestrator analyzes the CPU usage.
+3.  If condition is met, sends command `python backup_script.py` to Cloud node.
+4.  Result: A coordinated action across two different physical machines.
+
+---
+
+## 🛠️ Tech Stack
+
+### Core Technologies
+*   **Frontend**: Gradio 6.0 (Python)
+*   **Backend**: FastAPI, Uvicorn
+*   **Protocol**: JSON-RPC 2.0 (MCP Standard)
+*   **AI Models**: OpenAI, Anthropic, Gemini, Mistral, Llama (via Ollama)
+
+### Key Libraries
+*   `pydantic` - Data validation and settings management
+*   `httpx` - Async HTTP client for node communication
+*   `pyyaml` - Configuration file parsing
+*   `rich` - Terminal UI for debugging
+
+### Compatibility
+*   **Primary Support**: macOS, Linux (Debian/Ubuntu/Kali)
+*   **Windows Support**: Recommended via **WSL2**. Native Windows support is experimental.
+
+---
+
+## 🔧 Troubleshooting
+
+### Port Already in Use
+**Error**: `Address already in use: 7860`
+
+**Solution**: The system automatically finds the next open port. Check the terminal output for the correct URL (e.g., `http://127.0.0.1:7861`).
+
+### Node Not Connecting
+**Error**: "Could not connect to node"
+
+**Solutions**:
+1.  Verify the node is running: `ps aux | grep nacc-node`
+2.  Check firewall settings allow port 8001
+3.  Confirm both machines are on the same local network
+4.  Try connecting to the node's IP directly in a browser: `http://192.168.1.15:8001/healthz`
+
+### Permission Denied
+**Error**: `Permission denied: './start_nacc.sh'`
+
+**Solution** (Mac/Linux):
+```bash
+chmod +x start_nacc.sh
+```
+
+### Missing Dependencies
+**Error**: `ModuleNotFoundError: No module named 'gradio'`
+
+**Solution**:
+```bash
+source .venv/bin/activate  # Activate virtual environment
+pip install -r requirements.txt
+```
+
+### API Key Issues
+**Error**: "Invalid API key"
+
+**Solutions**:
+1.  Verify your API key is correctly set in environment variables or UI settings
+2.  Try using the Blaxel backend (pre-configured)
+3.  Switch to local Ollama if you have it running
+
+---
+
+## 💻 Platform Compatibility
+
+### ✅ Fully Supported Platforms
+
+NACC was **built and extensively tested** on the following platforms:
+
+*   **macOS** (Primary development platform)
+*   **Linux** - Debian/Ubuntu/Kali (Tested on Kali Linux VM)
+
+These platforms provide the best experience with full feature support and stability.
+
+### ⚠️ Windows Compatibility Warning
+
+**NACC is NOT recommended for Windows** and may not work properly:
+
+*   **Built on macOS**: The entire system was developed and optimized for Unix-like environments
+*   **Tested on Linux**: All testing and verification was done on macOS and Kali Linux
+*   **Shell Dependencies**: Many core features rely on bash/sh commands that don't translate well to Windows
+*   **Path Handling**: File system operations use Unix path conventions
+
+**If you must use Windows**:
+1.  Use **WSL2 (Windows Subsystem for Linux)** - This is the ONLY supported way
+2.  Native Windows PowerShell/CMD is experimental and will likely fail
+3.  Expect compatibility issues with file operations and shell commands
+
+We strongly recommend using macOS or a Linux VM for the best experience.
+
+---
+
+## ❓ FAQ
+
+**Q: Do I need an API Key to use NACC?**
+
+A: NACC comes configured to use **Blaxel (Serverless)** by default for quick demos. For production, we recommend using your own OpenAI/Anthropic/Gemini key. You can also run **Ollama locally** (Docker required) for completely free, offline operation.
+
+**Q: Is NACC secure?**
+
+A: Yes, NACC is designed for **local network use only**. All communication between the Orchestrator and Nodes happens over your LAN. However, **do not expose Node ports to the public internet** without additional security layers (VPN/SSH Tunnel).
+
+**Q: Can I use NACC in production?**
+
+A: NACC is currently a hackathon project and proof-of-concept. While it's functional, we recommend additional hardening (authentication, encryption, rate limiting) before production use.
+
+**Q: I'm on Windows. Will this work?**
+
+A: Yes! We recommend using **WSL2** for the best experience. If running natively on Windows, some shell commands might need PowerShell equivalents.
+
+**Q: Can I control Windows machines?**
+
+A: Theoretically yes, but NACC is optimized for Unix-like systems (Mac/Linux). Windows support is experimental and may require custom tool configurations.
+
+**Q: How many nodes can I connect?**
+
+A: There's no hard limit, but we recommend starting with 2-5 nodes for optimal performance. The system is designed to scale horizontally.
+
+**Q: Can I use this with my existing automation scripts?**
+
+A: Absolutely! NACC Nodes can execute any script or command available on the target machine. Just use natural language to invoke them.
+
+---
+
+## ⚠️ Important Disclaimer
+
+**Local Network Only**: NACC is designed for local network environments. Nodes are discovered and controlled via direct IP connections. Ensure all your devices are connected to the same Wi-Fi or LAN. 
+
+**Security Note**: Do not expose the Node ports (default 8001) or Orchestrator ports (default 7860) to the public internet without additional security layers (VPN, SSH Tunnel, reverse proxy with authentication).
+
+**VM Recommendation**: For testing, we strongly recommend running Nodes in isolated Virtual Machines to prevent accidental system modifications.
+
+---
+
+## 👥 Team Members
+
+*   [Vasanthadithya-mundrathi](https://huggingface.co/Vasanthfeb13) - Creator & Lead Developer
+
+---
+
+## 🎯 Project Goals
+
+NACC was created for the **Hugging Face MCP Birthday Hackathon 2025** to demonstrate:
+
+1.  **MCP as a Universal Interface**: How the Model Context Protocol can unify disparate systems
+2.  **Natural Language Operations**: Making system administration accessible through conversation
+3.  **Distributed AI Orchestration**: Coordinating multiple agents across network boundaries
+4.  **Practical AI Applications**: Real-world use cases beyond chatbots
+
+---
+
+**Happy Hacking!** 🚀
+
+*Created for the Hugging Face MCP Birthday Hackathon 2025*
+*Built with ❤️ by Vasanthadithya Mundrathi*
+ 

app.py

@@ -0,0 +1,108 @@
+import os
+import sys
+import threading
+import time
+import uvicorn
+from fastapi import FastAPI
+import os
+import sys
+
+# --- MONKEY PATCH START ---
+# Fix for: ImportError: cannot import name 'HfFolder' from 'huggingface_hub'
+try:
+    import huggingface_hub
+    if not hasattr(huggingface_hub, "HfFolder"):
+        print("[NACC] Patching huggingface_hub.HfFolder for Gradio compatibility...")
+        class HfFolder:
+            @classmethod
+            def save_token(cls, token): 
+                pass
+            @classmethod
+            def get_token(cls): 
+                return os.getenv("HF_TOKEN")
+        huggingface_hub.HfFolder = HfFolder
+except ImportError:
+    pass
+# --- MONKEY PATCH END ---
+
+import gradio as gr
+from pathlib import Path
+
+# Add src to path
+sys.path.append(os.path.join(os.path.dirname(__file__), "src"))
+
+from nacc_orchestrator.server import build_service, create_app
+from nacc_orchestrator.config import NodeDefinition
+from nacc_ui.professional_ui_v2 import create_professional_ui_v2 as create_ui
+from nacc_node.tools import NodeServer
+from nacc_node.config import NodeConfig
+
+# 1. Build the Orchestrator Service
+service = build_service()
+
+# 2. Register the Local Node (Auto-Discovery for HF Space)
+local_node_def = NodeDefinition(
+    node_id="hf-space-local",
+    transport="http",
+    base_url="http://127.0.0.1:8001",
+    display_name="Local Node (Demo)",
+    tags=["local", "demo", "linux"],
+    priority=10
+)
+service.registry.add_node(local_node_def)
+print(f"✅ Auto-registered local node: {local_node_def.node_id}")
+
+# 3. Create the FastAPI App
+orchestrator_app = create_app(service)
+
+# 4. Create a combined FastAPI app
+app = FastAPI()
+app.mount("/api", orchestrator_app)
+
+def start_local_node():
+    """Start a local node in the background for the HF Space demo."""
+    print("🚀 Starting local NACC Node for HF Space...")
+    try:
+        # Create a temporary config for the local node
+        config = NodeConfig(
+            node_id="hf-space-local",
+            root_dir=Path.cwd(),
+            display_name="Local Node (Demo)",
+            tags=["local", "demo"],
+            allowed_commands=["ls", "cat", "echo", "grep", "head", "tail", "pwd", "whoami"],
+            sync_targets={}
+        )
+        
+        # Start node on port 8001
+        server = NodeServer(config, host="127.0.0.1", port=8001)
+        server.serve_forever()
+    except Exception as e:
+        print(f"❌ Failed to start local node: {e}")
+
+def start_orchestrator_api():
+    """Start the orchestrator API in the background."""
+    print("🧠 Starting NACC Orchestrator API...")
+    uvicorn.run(orchestrator_app, host="127.0.0.1", port=8000)
+
+# Start background services
+if __name__ == "__main__":
+    # 1. Start the Orchestrator API in a thread
+    api_thread = threading.Thread(target=start_orchestrator_api, daemon=True)
+    api_thread.start()
+    
+    # 2. Start a Local Node in a thread (so the Space works out-of-the-box)
+    node_thread = threading.Thread(target=start_local_node, daemon=True)
+    node_thread.start()
+    
+    # 3. Give services a moment to spin up
+    time.sleep(3)
+    
+    # 4. Launch the UI
+    print("💻 Launching NACC UI...")
+    # Pass the service instance to the UI if possible, or let it connect via API
+    # The UI connects to http://localhost:8000/api by default or via config
+    # We need to make sure the UI knows where the API is.
+    # professional_ui_v2.py likely reads config or defaults to localhost:8000
+    
+    demo = create_ui()
+    demo.launch(server_name="0.0.0.0", server_port=7860)

configs/node-config.example.yml

@@ -0,0 +1,16 @@
+# Example configuration for a single NACC node.
+# Copy this file and adjust the values for your environment.
+
+node_id: dev-node
+root_dir: ./demo-root
+description: Example development node
+tags:
+  - dev
+  - laptop
+allowed_commands:
+  - python
+  - ls
+  - cat
+  - echo
+sync_targets:
+  backup: ./backups/dev-node

configs/node-kali-vm.yml

@@ -0,0 +1,24 @@
+node_id: kali-vm
+root_dir: /home/vasanth/nacc-shared
+description: Kali Linux pentesting node in UTM
+tags: [kali, linux, pentesting, security, network-tools]
+allowed_commands:
+  - python3
+  - ls
+  - cat
+  - echo
+  - grep
+  - find
+  - nmap
+  - netcat
+  - nc
+  - ping
+  - curl
+  - wget
+  - uname
+  - whoami
+  - pwd
+  - hostname
+sync_targets:
+  backup: /home/vasanth/nacc-backup
+  shared: /home/vasanth/nacc-sync

configs/node-laptop.yml

@@ -0,0 +1,12 @@
+node_id: laptop-dev
+root_dir: ./demo-root/laptop
+description: Primary laptop sandbox
+tags: [laptop, mac]
+allowed_commands:
+  - python
+  - pytest
+  - ls
+  - cat
+  - echo
+sync_targets:
+  archive: ./backups/laptop

configs/node-linux-vm.yml

@@ -0,0 +1,12 @@
+node_id: linux-vm
+root_dir: /home/ubuntu/nacc-share
+description: Ubuntu VM
+tags: [linux, vm]
+allowed_commands:
+  - python3
+  - bash
+  - pytest
+  - tail
+  - echo
+sync_targets:
+  share: /home/ubuntu/nacc-share/snapshots

configs/node-windows-vm.yml

@@ -0,0 +1,10 @@
+node_id: windows-vm
+root_dir: C:/NACC/share
+description: Windows VM (PowerShell)
+tags: [windows, vm]
+allowed_commands:
+  - powershell
+  - cmd
+  - python
+sync_targets:
+  share: C:/NACC/share/backups

configs/orchestrator-blaxel-gemini.yml

@@ -0,0 +1,36 @@
+# NACC Orchestrator configuration for Testing Blaxel Gemini Backend
+nodes:
+  - node_id: kali-vm
+    transport: http
+    base_url: http://192.168.64.2:8765
+    description: Kali Linux pentesting VM in UTM
+    tags: [kali, linux, pentesting, security, vm]
+    priority: 10
+    
+  - node_id: macbook-local
+    transport: local
+    display_name: MacBook Pro (Host)
+    root_dir: /Users/vasanthadithya
+    description: Local macOS host machine
+    tags: [mac, laptop, host, local, macos]
+    priority: 5
+    allowed_commands: [ls, cat, echo, pwd, mkdir, touch, rm, mv, cp, grep, find, python3, node, npm, git, curl, wget, which, whoami, uname, hostname, date, sh, bash, brew, pip, pip3, head, tail, wc, sort, uniq, sed, awk, chmod, chown, ps, kill, df, du, tar, gzip, gunzip, zip, unzip, open, pbcopy, pbpaste]
+
+agent_backend:
+  kind: blaxel-gemini  # Testing Blaxel with Gemini-2.0-flash
+  # container_id: ${BLAXEL_API_KEY}
+  timeout: 30.0
+  environment:
+    workspace: vasanthfeb13
+    model: gemini-2.0-flash
+
+audit:
+  enabled: true
+  log_path: logs/audit-blaxel-gemini.log
+  max_size_mb: 100
+  keep_backups: 5
+
+security:
+  require_auth: false
+  allowed_ips: []
+  rate_limit_per_minute: 100

configs/orchestrator-blaxel-openai.yml

@@ -0,0 +1,78 @@
+agent_backend:
+  # container_id: ${BLAXEL_API_KEY} # Set in environment variables
+  environment:
+    model: sandbox-openai
+    workspace: vasanthfeb13
+  kind: blaxel-openai
+  timeout: 30.0
+audit:
+  enabled: true
+  keep_backups: 5
+  log_path: logs/audit-blaxel-openai.log
+  max_size_mb: 100
+nodes:
+- allowed_commands:
+  - ls
+  - cat
+  - echo
+  - pwd
+  - mkdir
+  - touch
+  - rm
+  - mv
+  - cp
+  - grep
+  - find
+  - python3
+  - node
+  - npm
+  - git
+  - curl
+  - wget
+  - which
+  - whoami
+  - uname
+  - hostname
+  - date
+  - sh
+  - bash
+  - brew
+  - pip
+  - pip3
+  - head
+  - tail
+  - wc
+  - sort
+  - uniq
+  - sed
+  - awk
+  - chmod
+  - chown
+  - ps
+  - kill
+  - df
+  - du
+  - tar
+  - gzip
+  - gunzip
+  - zip
+  - unzip
+  - open
+  - pbcopy
+  - pbpaste
+  description: Local macOS host machine
+  display_name: MacBook Pro (Host)
+  node_id: macbook-local
+  priority: 5
+  root_dir: /Users/vasanthadithya
+  tags:
+  - mac
+  - laptop
+  - host
+  - local
+  - macos
+  transport: local
+security:
+  allowed_ips: []
+  rate_limit_per_minute: 100
+  require_auth: false

configs/orchestrator-config.example.yml

@@ -0,0 +1,26 @@
+# Example orchestrator configuration
+orchestrator_id: demo-orchestrator
+nodes:
+  - node_id: local-dev
+    display_name: Local Dev Node
+    transport: local
+    root_dir: ./demo-root
+    tags: [dev, laptop]
+    priority: 10
+    allowed_commands: [python, ls, cat, echo]
+    sync_targets:
+      backup: ./backups/local-dev
+  - node_id: remote-http
+    display_name: Remote HTTP Node
+    transport: http
+    base_url: http://127.0.0.1:8765
+    tags: [remote, linux]
+    priority: 20
+agent_backend:
+  kind: docker-mistral
+  container_id: ccdfa597c64
+  command: ["python", "/opt/mistral/agent.py"]
+audit:
+  path: ./logs/audit.log
+  max_entries: 10000
+refresh_interval: 10

configs/orchestrator-local-demo.yml

@@ -0,0 +1,15 @@
+orchestrator_id: local-demo
+nodes:
+  - node_id: local-dev
+    display_name: Local Dev
+    transport: local
+    root_dir: .
+    tags: [dev, laptop]
+    allowed_commands:
+      - echo
+      - python
+      - ls
+agent_backend:
+  kind: local-heuristic
+audit:
+  path: ./logs/audit-local-demo.log

configs/orchestrator-modal.yml

@@ -0,0 +1,60 @@
+# NACC Orchestrator Configuration - Modal Backend (IBM Granite MoE)
+# Modal is the hackathon sponsor providing serverless GPU infrastructure
+# Uses IBM Granite-3.0-3B-A800M-Instruct (3.3B total, 800M active MoE)
+
+orchestrator_id: nacc-orchestrator-modal
+
+# Backend: Modal serverless GPU with IBM Granite MoE
+# For development: Run `modal serve src/nacc_orchestrator/modal_backend.py` first, then leave container_id blank
+# For production: Deploy with `modal deploy src/nacc_orchestrator/modal_backend.py` and set container_id to the web endpoint URL
+agent_backend:
+  kind: modal
+  container_id: null  # Leave blank for development mode (modal serve), or set to web endpoint URL for production
+  timeout: 120.0
+  environment:
+    model: ibm-granite/granite-3.0-3b-a800m-instruct
+    description: "Efficient MoE model with 32 experts, 800M active parameters"
+
+# Multi-node cluster configuration
+nodes:
+  # Local Mac node
+  - node_id: mac
+    display_name: "MacBook (localhost)"
+    transport: local
+    root_dir: /tmp/nacc-local
+    tags:
+      - development
+      - local
+      - macos
+    priority: 50
+    weight: 1.5
+
+  # Remote Kali Linux VM
+  - node_id: kali-vm
+    display_name: "Kali Linux VM"
+    transport: http
+    base_url: http://192.168.64.2:8765
+    auth_token: "nacc-secure-token-2024"
+    tags:
+      - security
+      - linux
+      - remote
+      - pentesting
+    priority: 100
+    weight: 1.0
+    allowed_commands:
+      - nmap
+      - netcat
+      - curl
+      - wget
+      - ssh
+      - python3
+      - bash
+
+# Audit logging
+audit:
+  path: logs/audit-modal.log
+  max_entries: 100000
+
+# Node health check interval
+refresh_interval: 10.0

configs/orchestrator-three-node.yml

@@ -0,0 +1,26 @@
+orchestrator_id: demo-three-node
+nodes:
+  - node_id: laptop-dev
+    display_name: Laptop Sandbox
+    transport: local
+    root_dir: ./demo-root/laptop
+    tags: [mac, laptop]
+    priority: 5
+  - node_id: linux-vm
+    display_name: Linux VM
+    transport: http
+    base_url: http://127.0.0.1:9876
+    tags: [linux, vm]
+    priority: 10
+    auth_token: ${LINUX_VM_TOKEN:-}
+  - node_id: windows-vm
+    display_name: Windows VM
+    transport: http
+    base_url: http://127.0.0.1:9877
+    tags: [windows, vm]
+    priority: 15
+agent_backend:
+  kind: docker-mistral
+  container_id: ccdfa597c64
+audit:
+  path: ./logs/audit.log

configs/orchestrator-vms.yml

@@ -0,0 +1,35 @@
+# NACC Orchestrator configuration for Kali VM + Mac (local laptop coming soon)
+nodes:
+  - node_id: kali-vm
+    transport: http
+    base_url: http://192.168.64.2:8765
+    description: Kali Linux pentesting VM in UTM
+    tags: [kali, linux, pentesting, security, vm]
+    priority: 10
+    
+  - node_id: macbook-local
+    transport: local
+    display_name: MacBook Pro (Host)
+    root_dir: /Users/vasanthadithya
+    description: Local macOS host machine
+    tags: [mac, laptop, host, local, macos]
+    priority: 5
+    allowed_commands: [ls, cat, echo, pwd, mkdir, touch, rm, mv, cp, grep, find, python3, node, npm, git, curl, wget, which, whoami, uname, hostname, date, sh, bash, brew, pip, pip3, head, tail, wc, sort, uniq, sed, awk, chmod, chown, ps, kill, df, du, tar, gzip, gunzip, zip, unzip, open, pbcopy, pbpaste]
+
+agent_backend:
+  kind: docker-mistral  # Using Docker Desktop AI models
+  container_id: mistral-nemo  # Model name (not container ID)
+  timeout: 60.0  # Increased timeout for model warmup
+  max_tokens: 200  # Keep responses concise
+  environment: {}
+
+audit:
+  enabled: true
+  log_path: logs/audit-vms.log
+  max_size_mb: 100
+  keep_backups: 5
+
+security:
+  require_auth: false
+  allowed_ips: []
+  rate_limit_per_minute: 100

configs/orchestrator.yml

@@ -0,0 +1,61 @@
+agent_backend:
+  container_id: null
+  environment:
+    description: Modal serverless GPU with IBM Granite MoE (3.3B/800M active)
+    modal_app_id: ap-8PaCvfA0O7brdDuCMSuNRV
+    model: ibm-granite/granite-3.0-3b-a800m-instruct
+  kind: modal
+  timeout: 120.0
+audit:
+  max_entries: 50000
+  path: logs/audit.log
+nodes:
+- display_name: MacBook Pro (Local)
+  node_id: macbook-local
+  priority: 50
+  root_dir: /Users/vasanthadithya/nacc-workspace
+  tags:
+  - development
+  - local
+  - macos
+  transport: local
+  weight: 1.5
+- allowed_commands:
+  - ls
+  - cat
+  - pwd
+  - echo
+  - mkdir
+  - touch
+  - nmap
+  - netcat
+  - curl
+  - wget
+  - ssh
+  - python3
+  - bash
+  - nc
+  - ping
+  auth_token: nacc-secure-token-2024
+  base_url: http://192.168.64.2:8765
+  display_name: Kali Linux VM
+  node_id: kali-vm
+  priority: 100
+  tags:
+  - security
+  - linux
+  - remote
+  - pentesting
+  transport: http
+  weight: 1.0
+- base_url: !!python/object:pydantic.networks.HttpUrl
+    _url: !!python/object/new:pydantic_core._pydantic_core.Url
+    - http://127.0.0.1:8765/
+  display_name: Node-697444
+  id: ff8ee336-a8f4-476a-8507-e8ab0df92d49
+  tags:
+  - dynamic
+  - unknown
+  transport: http
+orchestrator_id: nacc-orchestrator
+refresh_interval: 10.0

configs/ui-config.example.yml

@@ -0,0 +1,5 @@
+# Example UI configuration
+orchestrator_url: http://127.0.0.1:8888
+host: 0.0.0.0
+port: 7860
+refresh_interval: 5

configs/ui-modal.yml

@@ -0,0 +1,5 @@
+# UI configuration for Modal backend
+orchestrator_url: http://127.0.0.1:8888
+host: 0.0.0.0
+port: 7860
+refresh_interval: 5

orchestrator-config.yml

@@ -0,0 +1,59 @@
+agent_backend:
+  container_id: null
+  environment:
+    description: Modal serverless GPU with IBM Granite MoE (3.3B/800M active)
+    modal_app_id: ap-8PaCvfA0O7brdDuCMSuNRV
+    model: ibm-granite/granite-3.0-3b-a800m-instruct
+  kind: modal
+  timeout: 120.0
+audit:
+  max_entries: 50000
+  path: logs/audit.log
+nodes:
+- display_name: MacBook Pro (Local)
+  node_id: macbook-local
+  priority: 50
+  root_dir: /Users/vasanthadithya/nacc-workspace
+  tags:
+  - development
+  - local
+  - macos
+  transport: local
+  weight: 1.5
+- allowed_commands:
+  - ls
+  - cat
+  - pwd
+  - echo
+  - mkdir
+  - touch
+  - nmap
+  - netcat
+  - curl
+  - wget
+  - ssh
+  - python3
+  - bash
+  - nc
+  - ping
+  auth_token: nacc-secure-token-2024
+  base_url: http://192.168.64.2:8765
+  display_name: Kali Linux VM
+  node_id: kali-vm
+  priority: 100
+  tags:
+  - security
+  - linux
+  - remote
+  - pentesting
+  transport: http
+  weight: 1.0
+- base_url: http://127.0.0.1:8765/
+  display_name: Node-697444
+  id: ff8ee336-a8f4-476a-8507-e8ab0df92d49
+  tags:
+  - dynamic
+  - unknown
+  transport: http
+orchestrator_id: nacc-orchestrator
+refresh_interval: 10.0

requirements.txt

@@ -0,0 +1,27 @@
+# NACC Core Dependencies
+fastapi>=0.115.0
+uvicorn>=0.30.0
+gradio==4.44.1  # Stable v4
+pydantic>=2.8.2
+pyyaml>=6.0.2
+requests>=2.32.0
+psutil>=6.0.0
+paramiko>=3.5.0
+pyjwt>=2.9.0
+python-multipart>=0.0.9
+huggingface_hub==0.24.6  # Explicitly pin to version with HfFolder
+
+# AI Backend Dependencies
+# Blaxel (Default) - No extra pip packages needed, uses HTTP
+
+# Optional backends (install if using)
+# modal>=0.63.0               # For Modal backend
+# google-generativeai>=0.3.0  # For Gemini backend
+# openai>=1.0.0               # For OpenAI backend
+
+# Development Dependencies
+pytest>=8.0.0
+pytest-cov>=4.0.0
+black>=24.0.0
+ruff>=0.6.0
+python-dotenv>=1.0.0

src/nacc_node/__init__.py

@@ -0,0 +1,25 @@
+"""NACC node MCP server package."""
+
+from .filesystem import FileMetadata, list_files, list_files_json
+from .tools import (
+	NodeServer,
+	list_files_tool,
+	read_file_tool,
+	write_file_tool,
+	execute_command_tool,
+	sync_files_tool,
+	get_node_info_tool,
+)
+
+__all__ = [
+	"FileMetadata",
+	"list_files",
+	"list_files_json",
+	"NodeServer",
+	"list_files_tool",
+	"read_file_tool",
+	"write_file_tool",
+	"execute_command_tool",
+	"sync_files_tool",
+	"get_node_info_tool",
+]

src/nacc_node/cli.py

@@ -0,0 +1,163 @@
+"""Command-line entry point for the NACC node server.
+
+Currently a stub that just prints configuration info; to be extended with
+actual MCP server startup logic.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+import sys
+
+from .filesystem import list_files
+from .config import load_node_config
+from .tools import NodeServer
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="NACC node MCP server")
+    subparsers = parser.add_subparsers(dest="command")
+
+    serve = subparsers.add_parser("serve", help="Start the MCP node server")
+    serve.add_argument("--host", default="0.0.0.0", help="Host/IP to bind (default 0.0.0.0)")
+    serve.add_argument("--port", type=int, default=8765, help="Port to listen on")
+    serve.add_argument(
+        "--config",
+        type=str,
+        default="node-config.yml",
+        help="Path to node configuration file",
+    )
+    serve.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Validate configuration and exit without starting the server",
+    )
+
+    init_parser = subparsers.add_parser("init", help="Initialize a new node and generate pairing code")
+
+    list_parser = subparsers.add_parser("list-files", help="List files on this node")
+    list_parser.add_argument("--path", default=".", help="Path to inspect")
+    list_parser.add_argument(
+        "--recursive",
+        action="store_true",
+        help="Recurse into subdirectories",
+    )
+    list_parser.add_argument(
+        "--filter",
+        dest="pattern",
+        default=None,
+        help="Glob filter applied to relative paths",
+    )
+    list_parser.add_argument(
+        "--with-hash",
+        action="store_true",
+        help="Compute sha256 for files (slower)",
+    )
+    list_parser.add_argument(
+        "--config",
+        type=str,
+        default=None,
+        help="Optional node-config file to scope the path to the node root",
+    )
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> None:
+    parser = _build_parser()
+    parsed_args = list(argv) if argv is not None else sys.argv[1:]
+    if not parsed_args or parsed_args[0].startswith("-"):
+        parsed_args = ["serve", *parsed_args]
+    args = parser.parse_args(parsed_args)
+
+    if args.command == "list-files":
+        root_override: Path | None = None
+        target_path = Path(args.path)
+        if args.config:
+            config = load_node_config(args.config)
+            root_override = config.root_dir
+            if not target_path.is_absolute():
+                target_path = (root_override / target_path).resolve()
+        files = list_files(
+            target_path,
+            recursive=args.recursive,
+            pattern=args.pattern,
+            include_hash=args.with_hash,
+            root=str(root_override) if root_override else None,
+        )
+        payload = {"files": [file.to_dict() for file in files], "count": len(files)}
+        print(json.dumps(payload, indent=2))
+        return
+
+    if args.command == "init":
+        import uuid
+        from .pairing import create_session
+        
+        # Generate defaults
+        node_id = str(uuid.uuid4())
+        root_dir = Path.cwd().resolve()
+        
+        # Create config structure
+        config_data = {
+            "node_id": node_id,
+            "root_dir": str(root_dir),
+            "display_name": f"Node-{node_id[:8]}",
+            "tags": ["generic"],
+            "allowed_commands": ["python", "ls", "cat", "echo", "grep"],
+            "sync_targets": {}
+        }
+        
+        # Generate pairing code
+        session = create_session(node_id)
+        
+        # Save config
+        output_path = Path("node-config.yml")
+        if output_path.exists():
+            print(f"Config file {output_path} already exists. Skipping creation.")
+        else:
+            import yaml
+            with open(output_path, "w") as f:
+                yaml.dump(config_data, f)
+            print(f"Created {output_path}")
+
+        print("\n" + "="*40)
+        print(f"🚀 Node Initialized: {config_data['display_name']}")
+        print(f"🆔 Node ID: {node_id}")
+        print(f"🔑 PAIRING CODE: {session.code}")
+        print("="*40)
+        print("\nRun this on your orchestrator to pair:")
+        print(f"  nacc-orchestrator register-node {session.code} --ip <THIS_NODE_IP>")
+        print("\n(Note: The code is for display only in this version. Use the ID/IP for manual registration if needed.)")
+        return
+
+    if args.command in (None, "serve"):
+        config_path = getattr(args, "config", "node-config.yml")
+        config = load_node_config(config_path)
+        if getattr(args, "dry_run", False):
+            summary = {
+                "node_id": config.node_id,
+                "root_dir": str(config.root_dir),
+                "tags": config.tags,
+                "allowed_commands": config.allowed_commands,
+                "sync_targets": {key: str(value) for key, value in config.sync_targets.items()},
+            }
+            print(json.dumps(summary, indent=2))
+            return
+
+        host = getattr(args, "host", "0.0.0.0")
+        port = getattr(args, "port", 8765)
+        server = NodeServer(config, host=host, port=port)
+        try:
+            server.serve_forever()
+        except KeyboardInterrupt:  # pragma: no cover - manual interrupt
+            print("\n[nacc-node] shutdown requested")
+            server.shutdown()
+        return
+
+    parser.error(f"Unknown command: {args.command}")
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()

src/nacc_node/config.py

@@ -0,0 +1,43 @@
+"""Configuration helpers for the NACC node server."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import yaml
+from pydantic import BaseModel, Field, field_validator
+
+
+class NodeConfig(BaseModel):
+    node_id: str = Field(..., description="Unique identifier for the node")
+    root_dir: Path = Field(..., description="Root directory exposed by the node")
+    tags: list[str] = Field(default_factory=list)
+    description: str | None = None
+    allowed_commands: list[str] = Field(
+        default_factory=lambda: ["python", "ls", "cat", "echo"],
+        description="Simple whitelist of commands allowed in ExecuteCommand",
+    )
+    sync_targets: dict[str, Path] = Field(
+        default_factory=dict,
+        description="Mapping of sync target names to directories",
+    )
+
+    @field_validator("root_dir", mode="before")
+    def _expand_root(cls, value: Any) -> Path:
+        return Path(value).expanduser().resolve()
+
+    @field_validator("sync_targets", mode="before")
+    def _expand_targets(cls, value: dict[str, Any]) -> dict[str, Path]:
+        if not value:
+            return {}
+        return {key: Path(path).expanduser().resolve() for key, path in value.items()}
+
+
+def load_node_config(path: str | Path) -> NodeConfig:
+    config_path = Path(path).expanduser().resolve()
+    if not config_path.exists():
+        raise FileNotFoundError(f"Node config not found: {config_path}")
+    with config_path.open("r", encoding="utf-8") as handle:
+        data = yaml.safe_load(handle) or {}
+    return NodeConfig(**data)

src/nacc_node/filesystem.py

@@ -0,0 +1,131 @@
+"""Filesystem tooling for the NACC node server.
+
+Provides the "ListFiles" capability that other components (orchestrator, UI,
+CLI) can call directly. This will later be wrapped in MCP transport but
+remains a simple Python module for local development and testing.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, asdict
+from fnmatch import fnmatch
+from pathlib import Path
+from typing import Iterable
+import hashlib
+import json
+import os
+import time
+
+
+@dataclass(slots=True)
+class FileMetadata:
+    """Serializable metadata for a single filesystem entry."""
+
+    path: str
+    relative_path: str
+    is_dir: bool
+    size: int | None
+    modified: float
+    hash: str | None = None
+
+    def to_dict(self) -> dict[str, object]:
+        return asdict(self)
+
+
+class FileSystemError(RuntimeError):
+    """Raised when a filesystem operation fails unexpectedly."""
+
+
+def hash_file(path: Path, chunk_size: int = 1 << 16) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as handle:
+        for chunk in iter(lambda: handle.read(chunk_size), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def iter_entries(root: Path, recursive: bool) -> Iterable[Path]:
+    if root.is_file():
+        yield root
+        return
+
+    yield root
+    if recursive:
+        yield from root.rglob("*")
+    else:
+        for child in root.iterdir():
+            yield child
+
+
+def list_files(
+    path: str | os.PathLike[str],
+    *,
+    recursive: bool = False,
+    pattern: str | None = None,
+    include_hash: bool = False,
+    root: str | None = None,
+) -> list[FileMetadata]:
+    """Return metadata for files/directories under ``path``.
+
+    Parameters
+    ----------
+    path: str | PathLike
+        Root path to inspect.
+    recursive: bool
+        Whether to recurse into subdirectories (default False).
+    pattern: str | None
+        Optional glob-style pattern matching against the relative path.
+    include_hash: bool
+        If True, compute sha256 for regular files.
+    root: str | None
+        Custom root to compute ``relative_path``; defaults to ``path`` when it
+        points to a directory, or the parent directory when pointing to a file.
+    """
+
+    target = Path(path).expanduser().resolve()
+    if not target.exists():
+        raise FileNotFoundError(f"Path does not exist: {target}")
+
+    root_path = Path(root).expanduser().resolve() if root else (target if target.is_dir() else target.parent)
+    results: list[FileMetadata] = []
+
+    for entry in iter_entries(target, recursive):
+        rel = os.path.relpath(entry, root_path)
+        if pattern and not (fnmatch(rel, pattern) or fnmatch(entry.name, pattern)):
+            continue
+
+        stat_info = entry.stat()
+        is_dir = entry.is_dir()
+        size = None if is_dir else stat_info.st_size
+        modified = stat_info.st_mtime
+
+        file_hash: str | None = None
+        if include_hash and not is_dir:
+            try:
+                file_hash = hash_file(entry)
+            except OSError as exc:  # pragma: no cover (hard to trigger reliably)
+                raise FileSystemError(f"Failed to hash {entry}: {exc}") from exc
+
+        results.append(
+            FileMetadata(
+                path=str(entry),
+                relative_path=rel,
+                is_dir=is_dir,
+                size=size,
+                modified=modified,
+                hash=file_hash,
+            )
+        )
+
+    results.sort(key=lambda meta: meta.relative_path)
+    return results
+
+
+def list_files_json(**kwargs) -> str:
+    files = list_files(**kwargs)
+    payload = {
+        "generated_at": time.time(),
+        "count": len(files),
+        "files": [f.to_dict() for f in files],
+    }
+    return json.dumps(payload, indent=2)

src/nacc_node/pairing.py

@@ -0,0 +1,37 @@
+"""
+Node Pairing Logic
+Generates and verifies 6-digit pairing codes for secure node initialization.
+"""
+
+import secrets
+import string
+import time
+from dataclasses import dataclass
+from typing import Optional
+
+@dataclass
+class PairingSession:
+    code: str
+    node_id: str
+    created_at: float
+    expires_at: float
+
+    @property
+    def is_expired(self) -> bool:
+        return time.time() > self.expires_at
+
+def generate_pairing_code(length: int = 6) -> str:
+    """Generate a secure random numeric code."""
+    alphabet = string.digits
+    return ''.join(secrets.choice(alphabet) for _ in range(length))
+
+def create_session(node_id: str, ttl_seconds: int = 300) -> PairingSession:
+    """Create a new pairing session with a unique code."""
+    code = generate_pairing_code()
+    now = time.time()
+    return PairingSession(
+        code=code,
+        node_id=node_id,
+        created_at=now,
+        expires_at=now + ttl_seconds
+    )

src/nacc_node/tools.py

@@ -0,0 +1,637 @@
+"""Node MCP tool implementations and lightweight HTTP server."""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import platform
+import shlex
+import shutil
+import subprocess
+import time
+from dataclasses import dataclass
+from http import HTTPStatus
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
+from typing import Any, Callable, Dict
+
+import psutil
+from pydantic import BaseModel, Field, ValidationError
+
+from .config import NodeConfig
+from .filesystem import hash_file, list_files
+
+logger = logging.getLogger(__name__)
+
+ToolFunc = Callable[[NodeConfig, dict[str, Any]], dict[str, Any]]
+
+
+def _resolve_within_root(root: Path, requested: str) -> Path:
+    candidate = Path(requested)
+    candidate = candidate.expanduser()
+    if not candidate.is_absolute():
+        candidate = (root / candidate).resolve()
+    else:
+        candidate = candidate.resolve()
+
+    try:
+        candidate.relative_to(root)
+    except ValueError as exc:  # pragma: no cover - defensive guard
+        raise PermissionError(f"Requested path escapes root: {candidate}") from exc
+    return candidate
+
+
+class ListFilesRequest(BaseModel):
+    path: str = "."
+    recursive: bool = False
+    pattern: str | None = None
+    include_hash: bool = False
+    limit: int | None = Field(default=None, ge=1, le=20_000)
+
+
+class ReadFileRequest(BaseModel):
+    path: str
+    encoding: str | None = "utf-8"
+    max_bytes: int | None = Field(default=None, ge=1, le=50_000_000)
+
+
+class WriteFileRequest(BaseModel):
+    path: str
+    content: str
+    encoding: str = "utf-8"
+    overwrite: bool = False
+    create_dirs: bool = True
+    backup: bool = True
+
+
+class ExecuteCommandRequest(BaseModel):
+    command: list[str] | str
+    timeout: float = Field(default=60.0, gt=0, le=600)
+    env: dict[str, str] = Field(default_factory=dict)
+    cwd: str | None = None
+
+
+class SyncFilesRequest(BaseModel):
+    source_path: str
+    targets: list[str] = Field(..., min_length=1)
+    strategy: str = Field(default="mirror", pattern=r"^(mirror|append)$")
+
+
+class GetNodeInfoRequest(BaseModel):
+    include_processes: bool = False
+
+
+@dataclass(slots=True)
+class SyncReport:
+    target: str
+    dest_path: str
+    files_synced: int
+    bytes_copied: int
+    duration: float
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "target": self.target,
+            "dest_path": self.dest_path,
+            "files_synced": self.files_synced,
+            "bytes_copied": self.bytes_copied,
+            "duration": self.duration,
+        }
+
+
+def list_files_tool(config: NodeConfig, payload: dict[str, Any]) -> dict[str, Any]:
+    request = ListFilesRequest.model_validate(payload)
+    target = _resolve_within_root(config.root_dir, request.path)
+    files = list_files(
+        target,
+        recursive=request.recursive,
+        pattern=request.pattern,
+        include_hash=request.include_hash,
+        root=config.root_dir,
+    )
+    if request.limit is not None:
+        files = files[: request.limit]
+    return {"files": [file.to_dict() for file in files], "count": len(files)}
+
+
+def read_file_tool(config: NodeConfig, payload: dict[str, Any]) -> dict[str, Any]:
+    request = ReadFileRequest.model_validate(payload)
+    target = _resolve_within_root(config.root_dir, request.path)
+    if not target.exists():
+        raise FileNotFoundError(str(target))
+    if target.is_dir():
+        raise IsADirectoryError(str(target))
+
+    data = target.read_bytes()
+    if request.max_bytes and len(data) > request.max_bytes:
+        raise ValueError("File exceeds max_bytes limit")
+
+    content: str | None = None
+    if request.encoding:
+        content = data.decode(request.encoding)
+    return {
+        "path": str(target.relative_to(config.root_dir)),
+        "size": len(data),
+        "hash": hash_file(target),
+        "content": content,
+    }
+
+
+def write_file_tool(config: NodeConfig, payload: dict[str, Any]) -> dict[str, Any]:
+    request = WriteFileRequest.model_validate(payload)
+    target = _resolve_within_root(config.root_dir, request.path)
+    target.parent.mkdir(parents=True, exist_ok=request.create_dirs)
+
+    backup_path: Path | None = None
+    if target.exists():
+        if not request.overwrite:
+            raise FileExistsError(str(target))
+        if request.backup:
+            timestamp = int(time.time())
+            backup_path = target.parent / f"{target.name}.bak.{timestamp}"
+            shutil.copy2(target, backup_path)
+
+    data = request.content.encode(request.encoding)
+    target.write_bytes(data)
+    file_hash = hash_file(target)
+    return {
+        "success": True,
+        "path": str(target.relative_to(config.root_dir)),
+        "bytes_written": len(data),
+        "hash": file_hash,
+        "backup_path": str(backup_path) if backup_path else None,
+        "message": f"File written successfully: {target.relative_to(config.root_dir)}"
+    }
+
+
+def execute_command_tool(config: NodeConfig, payload: dict[str, Any]) -> dict[str, Any]:
+    request = ExecuteCommandRequest.model_validate(payload)
+    if isinstance(request.command, str):
+        command = shlex.split(request.command)
+    else:
+        command = request.command
+
+    if not command:
+        raise ValueError("Command cannot be empty")
+
+    base_cmd = Path(command[0]).name
+    if base_cmd not in config.allowed_commands:
+        raise PermissionError(f"Command '{base_cmd}' not on allow list")
+
+    cwd = _resolve_within_root(config.root_dir, request.cwd) if request.cwd else config.root_dir
+
+    env = os.environ.copy()
+    env.update({key: value for key, value in request.env.items() if isinstance(value, str)})
+
+    started = time.time()
+    proc = subprocess.run(
+        command,
+        cwd=str(cwd),
+        env=env,
+        capture_output=True,
+        text=True,
+        timeout=request.timeout,
+    )
+    duration = time.time() - started
+    return {
+        "command": command,
+        "stdout": proc.stdout,
+        "stderr": proc.stderr,
+        "exit_code": proc.returncode,
+        "duration": duration,
+        "cwd": str(cwd.relative_to(config.root_dir)),
+    }
+
+
+def sync_files_tool(config: NodeConfig, payload: dict[str, Any]) -> dict[str, Any]:
+    request = SyncFilesRequest.model_validate(payload)
+    source = _resolve_within_root(config.root_dir, request.source_path)
+    if not source.exists():
+        raise FileNotFoundError(str(source))
+
+    reports: list[SyncReport] = []
+    source_rel = source.relative_to(config.root_dir)
+
+    for target_name in request.targets:
+        if target_name not in config.sync_targets:
+            raise ValueError(f"Unknown sync target: {target_name}")
+        target_dir = config.sync_targets[target_name]
+        dest_root = target_dir / source_rel
+        dest_root.parent.mkdir(parents=True, exist_ok=True)
+
+        started = time.time()
+        files_synced, bytes_copied = _copy_path(source, dest_root, strategy=request.strategy)
+        duration = time.time() - started
+        reports.append(
+            SyncReport(
+                target=target_name,
+                dest_path=str(dest_root),
+                files_synced=files_synced,
+                bytes_copied=bytes_copied,
+                duration=duration,
+            )
+        )
+
+    return {
+        "source": str(source_rel),
+        "targets": [report.to_dict() for report in reports],
+    }
+
+
+def _copy_path(source: Path, dest: Path, *, strategy: str) -> tuple[int, int]:
+    files_synced = 0
+    bytes_copied = 0
+
+    if source.is_file():
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copy2(source, dest)
+        files_synced = 1
+        bytes_copied = source.stat().st_size
+        return files_synced, bytes_copied
+
+    if strategy == "mirror" and dest.exists():
+        shutil.rmtree(dest)
+
+    for src_file in source.rglob("*"):
+        if not src_file.is_file():
+            continue
+        rel = src_file.relative_to(source)
+        dest_file = dest / rel
+        dest_file.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copy2(src_file, dest_file)
+        files_synced += 1
+        bytes_copied += src_file.stat().st_size
+
+    return files_synced, bytes_copied
+
+
+def get_node_info_tool(config: NodeConfig, payload: dict[str, Any]) -> dict[str, Any]:
+    _ = GetNodeInfoRequest.model_validate(payload or {})
+    cpu = psutil.cpu_percent(interval=0.05)
+    mem = psutil.virtual_memory()
+    disk = psutil.disk_usage(str(config.root_dir))
+    boot_time = psutil.boot_time()
+
+    return {
+        "node_id": config.node_id,
+        "tags": config.tags,
+        "description": config.description,
+        "root_dir": str(config.root_dir),
+        "allowed_commands": config.allowed_commands,
+        "sync_targets": {key: str(value) for key, value in config.sync_targets.items()},
+        "metrics": {
+            "cpu_percent": cpu,
+            "memory_percent": mem.percent,
+            "memory_total": mem.total,
+            "disk_percent": disk.percent,
+            "disk_total": disk.total,
+            "uptime_seconds": time.time() - boot_time,
+        },
+        "platform": {
+            "system": platform.system(),
+            "release": platform.release(),
+            "version": platform.version(),
+            "machine": platform.machine(),
+            "python_version": platform.python_version(),
+        },
+        "timestamp": time.time(),
+    }
+
+
+class NodeServer:
+    """Minimal HTTP server that exposes node tools as JSON endpoints."""
+
+    def __init__(self, config: NodeConfig, *, host: str = "0.0.0.0", port: int = 8765):
+        self.config = config
+        self.host = host
+        self.port = port
+        self._httpd: ThreadingHTTPServer | None = None
+
+    def serve_forever(self) -> None:
+        handler = self._build_handler()
+        self._httpd = ThreadingHTTPServer((self.host, self.port), handler)
+        logger.info("[nacc-node] serving http://%s:%s", self.host, self.port)
+        try:
+            self._httpd.serve_forever()
+        finally:
+            self._httpd.server_close()
+            logger.info("[nacc-node] server stopped")
+
+    def shutdown(self) -> None:
+        if self._httpd:
+            self._httpd.shutdown()
+
+    def _build_handler(self) -> type[BaseHTTPRequestHandler]:
+        config = self.config
+        tools: Dict[str, ToolFunc] = {
+            "list-files": list_files_tool,
+            "read-file": read_file_tool,
+            "write-file": write_file_tool,
+            "execute-command": execute_command_tool,
+            "sync-files": sync_files_tool,
+            "get-node-info": get_node_info_tool,
+        }
+        max_body = 512 * 1024
+
+        class NodeRequestHandler(BaseHTTPRequestHandler):
+            server_version = "NACCNode/0.3"
+
+            def log_message(self, format: str, *args: Any) -> None:  # pragma: no cover - HTTP logging
+                logger.info("%s - %s", self.address_string(), format % args)
+
+            def _read_json_body(self) -> dict[str, Any]:
+                content_length = int(self.headers.get("Content-Length", 0))
+                if content_length > max_body:
+                    raise ValueError("Payload too large")
+                if content_length <= 0:
+                    return {}
+                body = self.rfile.read(content_length)
+                if not body:
+                    return {}
+                return json.loads(body.decode("utf-8"))
+
+            def _send_json(self, status: HTTPStatus, payload: dict[str, Any]) -> None:
+                data = json.dumps(payload).encode("utf-8")
+                self.send_response(status)
+                self.send_header("Content-Type", "application/json")
+                self.send_header("Content-Length", str(len(data)))
+                self.end_headers()
+                self.wfile.write(data)
+
+            def do_GET(self) -> None:  # noqa: N802 - required name
+                logger.info(f"GET request to: {self.path}")
+                
+                # Handle root path (ignore query params)
+                path_clean = self.path.split('?')[0]
+                
+                if path_clean == "/healthz":
+                    self._send_json(HTTPStatus.OK, {
+                        "status": "ok",
+                        "service": "nacc-node",
+                        "node_id": config.node_id
+                    })
+                    return
+                if path_clean == "/node":
+                    payload = get_node_info_tool(config, {})
+                    self._send_json(HTTPStatus.OK, payload)
+                    return
+                
+                if path_clean == "/" or path_clean == "/index.html" or path_clean == "/dashboard":
+                    # Serve the VM Dashboard
+                    html = """
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>NACC VM Node</title>
+    <style>
+        body { font-family: 'Courier New', Courier, monospace; background: #0d1117; color: #c9d1d9; margin: 0; padding: 20px; }
+        .container { max-width: 1000px; margin: 0 auto; }
+        h1 { border-bottom: 1px solid #30363d; padding-bottom: 10px; color: #58a6ff; font-family: -apple-system, sans-serif; }
+        .card { background: #161b22; border: 1px solid #30363d; border-radius: 6px; padding: 20px; margin-bottom: 20px; }
+        .card h2 { margin-top: 0; font-size: 1.2em; color: #79c0ff; font-family: -apple-system, sans-serif; }
+        
+        /* Terminal Styles */
+        .terminal { background: #010409; padding: 15px; border-radius: 6px; border: 1px solid #30363d; height: 400px; overflow-y: auto; display: flex; flex-direction: column; }
+        .output { flex-grow: 1; white-space: pre-wrap; word-break: break-all; }
+        .input-line { display: flex; align-items: center; margin-top: 10px; border-top: 1px solid #21262d; padding-top: 10px; }
+        .prompt { color: #3fb950; margin-right: 10px; font-weight: bold; }
+        input { background: transparent; border: none; color: #c9d1d9; flex-grow: 1; font-family: inherit; font-size: 1em; outline: none; }
+        
+        .status-ok { color: #3fb950; font-weight: bold; }
+        table { width: 100%; border-collapse: collapse; font-family: -apple-system, sans-serif; }
+        th, td { text-align: left; padding: 8px; border-bottom: 1px solid #21262d; }
+        th { color: #8b949e; }
+        tr:hover { background: #21262d; }
+    </style>
+</head>
+<body>
+    <div class="container">
+        <h1>🖥️ NACC Virtual Machine Node</h1>
+        
+        <div class="card">
+            <h2>Status: <span class="status-ok">RUNNING</span></h2>
+            <div id="node-info" style="font-family: -apple-system, sans-serif;">Loading system info...</div>
+        </div>
+
+        <div class="card">
+            <h2>💻 Secure Terminal</h2>
+            <div class="terminal" id="terminal" onclick="document.getElementById('cmd-input').focus()">
+                <div class="output" id="output">
+                    Welcome to NACC VM Secure Terminal.
+                    Allowed commands: ls, cat, pwd, echo, grep, find, head, tail, tree, whoami, id
+                    Type 'help' for info.
+                </div>
+                <div class="input-line">
+                    <span class="prompt" id="prompt">user@vm:~$</span>
+                    <input type="text" id="cmd-input" autocomplete="off" spellcheck="false">
+                </div>
+            </div>
+        </div>
+
+        <div class="card">
+            <h2>📂 File Browser</h2>
+            <button onclick="listFiles()" style="background: #238636; color: white; border: none; padding: 6px 12px; border-radius: 6px; cursor: pointer;">Refresh Current Dir</button>
+            <div id="file-list" style="margin-top: 10px;"></div>
+        </div>
+    </div>
+
+    <script>
+        let currentDir = ".";
+        const input = document.getElementById('cmd-input');
+        const output = document.getElementById('output');
+        const prompt = document.getElementById('prompt');
+
+        input.addEventListener('keydown', async (e) => {
+            if (e.key === 'Enter') {
+                const cmd = input.value.trim();
+                input.value = '';
+                if (!cmd) return;
+
+                appendToOutput(prompt.innerText + ' ' + cmd);
+                await processCommand(cmd);
+                // Keep focus
+                input.focus();
+                // Scroll to bottom
+                document.getElementById('terminal').scrollTop = document.getElementById('terminal').scrollHeight;
+            }
+        });
+
+        function appendToOutput(text) {
+            const div = document.createElement('div');
+            div.innerText = text;
+            output.appendChild(div);
+        }
+
+        async function processCommand(cmd) {
+            const args = cmd.split(' ');
+            const baseCmd = args[0];
+
+            if (baseCmd === 'clear') {
+                output.innerHTML = '';
+                return;
+            }
+
+            if (baseCmd === 'help') {
+                appendToOutput("Available commands: ls, cat, pwd, echo, grep, find, head, tail, tree, whoami, id\\nNavigation: cd <path>");
+                return;
+            }
+
+            if (baseCmd === 'cd') {
+                const target = args[1] || '.';
+                // Optimistic update, verify with pwd/ls later if needed
+                // Simple path joining logic for display
+                if (target === '..') {
+                    // Very basic parent handling
+                    const parts = currentDir.split('/');
+                    parts.pop();
+                    currentDir = parts.join('/') || '.';
+                } else if (target.startsWith('/')) {
+                    currentDir = target;
+                } else {
+                    currentDir = (currentDir === '.' ? '' : currentDir + '/') + target;
+                }
+                updatePrompt();
+                // Verify path by running ls
+                try {
+                    await execute('ls', currentDir);
+                } catch (e) {
+                    appendToOutput("Error: Directory not found (or access denied)");
+                    // Revert? Nah, let user fix it
+                }
+                listFiles(); // Update file browser too
+                return;
+            }
+
+            // Execute on server
+            await execute(cmd, currentDir);
+        }
+
+        async function execute(command, cwd) {
+            try {
+                const res = await fetch('/tools/execute-command', {
+                    method: 'POST',
+                    headers: {'Content-Type': 'application/json'},
+                    body: JSON.stringify({command: command, cwd: cwd})
+                });
+                const data = await res.json();
+                
+                if (data.error) {
+                    appendToOutput("Error: " + data.error);
+                } else {
+                    if (data.stdout) appendToOutput(data.stdout);
+                    if (data.stderr) appendToOutput("Stderr: " + data.stderr);
+                    if (data.exit_code !== 0) appendToOutput("[Exit: " + data.exit_code + "]");
+                    
+                    // Update cwd from server response if available (it returns the resolved cwd)
+                    if (data.cwd) {
+                        // currentDir = data.cwd; // Optional: sync with server truth
+                        // updatePrompt();
+                    }
+                }
+            } catch (e) {
+                appendToOutput("Network Error: " + e.message);
+            }
+        }
+
+        function updatePrompt() {
+            prompt.innerText = `user@vm:${currentDir}$`;
+        }
+
+        async function fetchNodeInfo() {
+            try {
+                const res = await fetch('/node');
+                const data = await res.json();
+                document.getElementById('node-info').innerHTML = `
+                    <p><strong>Node ID:</strong> ${data.node_id}</p>
+                    <p><strong>OS:</strong> ${data.platform.system} ${data.platform.release}</p>
+                    <p><strong>Root:</strong> ${data.root_dir}</p>
+                `;
+            } catch (e) {}
+        }
+
+        async function listFiles() {
+            try {
+                const res = await fetch('/tools/list-files', {
+                    method: 'POST',
+                    headers: {'Content-Type': 'application/json'},
+                    body: JSON.stringify({path: currentDir, recursive: false})
+                });
+                const data = await res.json();
+                if (data.files) {
+                    let html = '<table><tr><th>Name</th><th>Type</th><th>Size</th></tr>';
+                    data.files.forEach(f => {
+                        html += `<tr><td>${f.name}</td><td>${f.is_dir ? 'DIR' : 'FILE'}</td><td>${f.size || '-'}</td></tr>`;
+                    });
+                    html += '</table>';
+                    document.getElementById('file-list').innerHTML = html;
+                } else {
+                    document.getElementById('file-list').innerText = "Error listing files: " + JSON.stringify(data);
+                }
+            } catch (e) {
+                document.getElementById('file-list').innerText = 'Error: ' + e.message;
+            }
+        }
+
+        // Init
+        fetchNodeInfo();
+        listFiles();
+    </script>
+</body>
+</html>
+                    """
+                    self.send_response(HTTPStatus.OK)
+                    self.send_header("Content-Type", "text/html")
+                    self.send_header("Content-Length", str(len(html)))
+                    self.end_headers()
+                    self.wfile.write(html.encode("utf-8"))
+                    return
+
+                self._send_json(HTTPStatus.NOT_FOUND, {"error": "Not Found"})
+
+            def do_POST(self) -> None:  # noqa: N802 - required name
+                if not self.path.startswith("/tools/"):
+                    self._send_json(HTTPStatus.NOT_FOUND, {"error": "Unknown endpoint"})
+                    return
+                tool_name = self.path.split("/", 2)[-1]
+                tool = tools.get(tool_name)
+                if not tool:
+                    self._send_json(HTTPStatus.NOT_FOUND, {"error": f"Tool '{tool_name}' not available"})
+                    return
+
+                try:
+                    payload = self._read_json_body()
+                    result = tool(config, payload)
+                except json.JSONDecodeError as exc:
+                    self._send_json(HTTPStatus.BAD_REQUEST, {"error": "Invalid JSON", "details": str(exc)})
+                    return
+                except ValidationError as exc:
+                    self._send_json(HTTPStatus.BAD_REQUEST, {"error": "Validation failed", "details": exc.errors()})
+                    return
+                except PermissionError as exc:
+                    self._send_json(HTTPStatus.FORBIDDEN, {"error": str(exc)})
+                    return
+                except FileNotFoundError as exc:
+                    self._send_json(HTTPStatus.NOT_FOUND, {"error": str(exc)})
+                    return
+                except Exception as exc:  # pragma: no cover - defensive guard
+                    logger.exception("Tool '%s' crashed", tool_name)
+                    self._send_json(HTTPStatus.INTERNAL_SERVER_ERROR, {"error": str(exc)})
+                    return
+
+                self._send_json(HTTPStatus.OK, result)
+
+        return NodeRequestHandler
+
+
+__all__ = [
+    "NodeServer",
+    "list_files_tool",
+    "read_file_tool",
+    "write_file_tool",
+    "execute_command_tool",
+    "sync_files_tool",
+    "get_node_info_tool",
+]

src/nacc_orchestrator/__init__.py

@@ -0,0 +1,4 @@
+"""NACC orchestrator package.
+
+Responsible for node registry, MCP calls to nodes, and agent coordination.
+"""