🛡️ localagent

The Zero-Trust, Security-First Local LLM Agent for Developers

Local Inference • Model Context Protocol (MCP) • Pre-Execution Path Jailing • SHA-256 Audit Chaining

---

💡 Why localagent?

Most current LLM agent frameworks operate with unrestricted host permissions — allowing hallucinations, bad tool calls, or indirect prompt injection to execute arbitrary shell commands or overwrite system files.

localagent is a terminal-native AI agent built from the ground up in Go with a Zero-Trust Security Architecture:

• 🔒 Zero Cloud Lock-In: Runs 100% locally via Ollama. No API keys or external server calls required.
• 🛡️ Pre-Execution Path Jailing: All file paths are canonicalized (EvalSymlinks) and checked against workspace bounds before any disk access.
• 🚫 Command Injection Prevention: Rejects shell string execution (sh -c) in favor of direct argument vectors with token & flag sanitization (git -C, ;&|><$).
• 📦 OS-Level Isolation: Supports Linux bubblewrap (bwrap) user namespaces with default network isolation (outbound sockets blocked).
• 🔗 Tamper-Evident SHA-256 Audit Log: Every tool proposal, policy check, user approval, and execution output is recorded in an immutable, cryptographically chained JSONL log.

---

🏛️ System Architecture

graph TD
    User([User Terminal]) -->|Prompt| CLI[cmd/localagent]
    CLI --> Agent[internal/agent Core ReAct Loop]
    
    subgraph Local LLM Backend
        Ollama[Ollama Server :11434]
    end
    
    Agent <-->|Chat & Function Calls| Ollama
    
    subgraph Defense-in-Depth Security Layer
        Sandbox[internal/sandbox Engine]
        Audit[internal/audit Logger]
    end
    
    Agent -->|Tool Proposal| Sandbox
    Sandbox -->|Path Jailing & bwrap Wrap| Isolation[Bubblewrap / OS Sandbox]
    Sandbox -->|Log Action| Audit
    Audit -->|SHA-256 Hash Chain| LogFile[(audit.jsonl)]
    
    subgraph MCP Tool Orchestration
        MCPClient[internal/mcp Client]
        FS[Filesystem MCP Server]
        Git[Git MCP Server]
        Shell[Shell MCP Server]
    end
    
    Isolation -->|Stdio JSON-RPC| MCPClient
    MCPClient <--> FS
    MCPClient <--> Git
    MCPClient <--> Shell

Loading

---

💻 Terminal Experience

$ ./localagent -model llama3.2 -workspace ./my-codebase

==================================================
🛡️  localagent: Security-First Local LLM Agent
==================================================
• Ollama Model : llama3.2
• Workspace    : /home/dev/my-codebase
• Audit Log    : audit.jsonl
• Sandbox Mode : basic
--------------------------------------------------

🤖 localagent [llama3.2] initialized.
Workspace: /home/dev/my-codebase
Type 'exit' or 'quit' to quit.

localagent > Analyze main.go and write unit tests in main_test.go

⚠️  [USER APPROVAL REQUIRED]
Tool: write_file
Arguments:
{
  "path": "/home/dev/my-codebase/main_test.go",
  "content": "package main..."
}
Do you want to proceed? [y/N]: y
✅ Tool 'write_file' completed.

---

🛡️ Sandbox Security Modes & Network Isolation

localagent supports two security modes controlled via CLI flags:

Mode	Flag	Description & Network Policy	Supported OS
basic (Default)	--sandbox-mode=basic	Cross-Platform Application Validation. Enforces strict canonical path jailing (EvalSymlinks), AST command binary whitelisting, directory flag validation (git -C), and argument sanitization.	Windows, macOS, Linux
strict	--sandbox-mode=strict	OS-Level Process Isolation. Wraps tool sub-processes in Linux bubblewrap (bwrap) user namespaces. Network access is isolated by default. Pass --allow-network to opt-in.	Linux (Falls back to basic on macOS/Windows)

---

🔗 Tamper-Evident SHA-256 Audit Log Chaining

Every event is written to audit.jsonl with SHA-256 cryptographic hash chaining (prev_hash and entry_hash).

Verify Audit Log Chain Integrity

./localagent -verify-audit audit.jsonl

• Intact Log Response:

  ✅ AUDIT LOG INTACT. Cryptographic chain verified across 14 entries.
  🔒 Tail SHA-256 Hash: 8f3c7b9e1d2a4f5...
  

• Tampered Log Response:

  ❌ AUDIT LOG CORRUPTED OR TAMPERED! Verification failed: line 4 entry_hash does not match computed digest
  

---

🧪 Security Verification & Escape Demo

Run our automated adversarial verification suite:

chmod +x demo/escape_attempts.sh
./demo/escape_attempts.sh

Attack Vector	Target Payload	Result	Primary Defense Layer
System File Access	~/.ssh/id_rsa	🔴 BLOCKED	Absolute Path Canonicalization
Destructive Command	rm -rf /	🔴 BLOCKED	AST Binary Whitelist & Command Sanitizer
Path Traversal	../../etc/passwd	🔴 BLOCKED	Prefix Boundary Matching (filepath.Rel)
Symlink Escape	symlink -> /etc/passwd	🔴 BLOCKED	Symlink Evaluation (filepath.EvalSymlinks)

Detailed attack reports available in demo/SECURITY_DEMO.md.

---

🚀 Quick Start Guide

1. Prerequisites

• Go 1.22+
• Ollama running locally (ollama run llama3.2)
• (Optional) Bubblewrap for Linux strict mode (sudo apt install bubblewrap)

2. Installation

git clone https://github.com/GunaTeja777/Local-first-LLM-Agent-with-MCP-Tool-Orchestration.git
cd Local-first-LLM-Agent-with-MCP-Tool-Orchestration
go build -o localagent ./cmd/localagent

3. Usage Examples

# Basic Cross-Platform Mode (Default)
./localagent -model llama3.2 -workspace ./my-project

# Strict Mode with Default Network Isolation (No outbound sockets)
./localagent -model llama3.2 -workspace ./my-project --sandbox-mode strict

# Strict Mode with Opt-In Network Access
./localagent -model llama3.2 -workspace ./my-project --sandbox-mode strict --allow-network

# Auto-Approve Safe Operations (Non-Interactive)
./localagent -model llama3.2 -workspace ./my-project -y

# Verify Cryptographic Log Chain Integrity
./localagent -verify-audit audit.jsonl

---

🔌 MCP Server Configuration (mcp_config.json)

localagent integrates natively with Model Context Protocol (MCP) servers:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
    },
    "git": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-git"]
    }
  }
}

Run with MCP servers:

./localagent -mcp-config mcp_config.example.json -workspace ./my-project

---

🎛️ CLI Options Reference

Flag	Default	Description
-model	llama3.2	Ollama model name (llama3.2, qwen2.5-coder, mistral)
-workspace	.	Target directory path jail root
-sandbox-mode	basic	Sandbox security mode (basic or strict)
-allow-network	false	Enable network access in strict sandbox mode
-audit-log	audit.jsonl	Output path for SHA-256 hash-chained JSONL log
-verify-audit	""	Verify audit log hash chain integrity and exit
-mcp-config	""	Path to MCP server configuration JSON file
-y	false	Skip interactive user prompt confirmation

---

📂 Project Structure

.
├── cmd/
│   └── localagent/       # CLI application entrypoint
├── demo/
│   ├── escape_attempts.sh# Adversarial attack verification script
│   └── SECURITY_DEMO.md  # Detailed security report & audit output
├── internal/
│   ├── agent/            # Core ReAct loop & Ollama orchestration
│   ├── audit/            # SHA-256 hash-chained audit logger & verifier
│   ├── config/           # Configuration parsing & validation
│   ├── mcp/              # MCP JSON-RPC stdio transport & tool mapper
│   ├── provider/         # Ollama HTTP API provider client
│   └── sandbox/          # Path jailing & basic/strict sandbox engines
├── CONTRIBUTING.md       # Developer contribution guidelines
├── LICENSE               # MIT License
├── README.md             # Project documentation
└── THREAT_MODEL.md       # Explicit threat model & security boundaries

---

🤝 Contributing & Security

Contributions are welcome! Please review CONTRIBUTING.md for local setup, testing standards, and pull request guidelines.

For security vulnerabilities or threat model discussions, refer to THREAT_MODEL.md.

---

📄 License

Distributed under the MIT License. See LICENSE for details.