GitHub - smouj/peanut-agent: 🥜Peanut Agent - PRO v0.1 Sistema de Agente Local con IA Avanzado - Haz que modelos pequeños funcionen como los grandes

The perfect companion for KiloCode — A production-ready AI Gateway with native MCP Server, Ollama local inference, Docker management, and enterprise-grade security. Zero API costs. Full privacy. Runs entirely on your machine.

🚀 Quick Start · 🔌 KiloCode Integration · 📖 Docs · 🏗️ Architecture · 🔒 Security

🇪🇸 Leer en Español · 🌐 GitHub Pages

✨ What is PeanutAgent?

PeanutAgent Enterprise is a full-stack AI Agent Management Platform that acts as a secure, intelligent gateway between your development tools and AI models. It bridges the gap between local LLMs and enterprise-grade tooling.

🔌 MCP Server (v2.0.0)

KiloCode discovers and uses your local Ollama models as native tools via the Model Context Protocol. 7 tools, 4 resources, 2 prompts — all spec-compliant.

🤖 Local AI Backend

Use PeanutAgent as a free, private AI backend for KiloCode. No API costs, no data leaving your machine. Supports qwen2.5, llama3.2, codellama, and any Ollama model.

🐳 Docker Management

Manage containers directly from KiloCode via MCP tools. List, start, stop, inspect, and stream logs — all from your IDE.

🔒 Enterprise Security

JWT httpOnly cookies · TOTP 2FA (RFC 6238) · scrypt password hashing · AES-256-GCM encrypted secrets · Immutable SHA-256 audit chain.

📊 Admin Dashboard

Next.js 15 dashboard with real-time metrics, agent management, Docker control, WebSocket terminal, and a dedicated KiloCode MCP integration page.

⚖️ Smart Load Balancing

OpenClaw Orchestrator implements Smooth Weighted Round-Robin (Nginx algorithm) across agents with health-based routing and per-agent metrics.

📸 Dashboard Screenshots

New Enterprise Dashboard — Redesigned with glassmorphism, neon effects, animated metrics, and a cyberpunk-inspired dark theme.

🖥️ Main Dashboard

🔐 Login Page

📊 Dashboard Overview (1440px)

Dashboard Features:

🌑 Dark glassmorphism design with backdrop blur effects
✨ Animated stat cards with sparkline charts and live counters
🟢 Real-time status indicators with neon glow effects
📈 System metrics with animated progress bars
⚡ Quick actions panel for instant navigation
🔒 Platform overview with security status
🤖 Agent list with health monitoring and latency display
🐳 Docker containers panel with live status
🎨 Cyber grid background with ambient glow effects

🏗️ Architecture

╔══════════════════════════════════════════════════════════════════════════╗
║                    PeanutAgent Enterprise v2.0.0                         ║
╠═══════════════════════════╦══════════════════════════════════════════════╣
║   Next.js 15 Dashboard    ║         Fastify API Gateway                  ║
║   (Port 3000)             ║         (Port 3001)                          ║
║   ─────────────────────   ║   ──────────────────────────────             ║
║   • Auth (2FA TOTP)       ║   • OpenClaw Orchestrator (SWRR)             ║
║   • Agent Management      ║   • JWT Auth (httpOnly cookies)              ║
║   • Docker Management     ║   • TOTP 2FA Verification                    ║
║   • Audit Log Viewer      ║   • Immutable Audit Chain (SHA-256)          ║
║   • WebSocket Terminal    ║   • Adaptive Rate Limiting                   ║
║   • KiloCode MCP Page     ║   • Docker Management API                    ║
║   • Settings              ║   • Kilo Code Bridge (AES-256-GCM)           ║
║                           ║   • MCP Server (7 tools, 4 resources)        ║
║                           ║   • Health Monitoring (30s intervals)        ║
║                           ║   • WebSocket Terminal                       ║
╠═══════════════════════════╩══════════════════════════════════════════════╣
║                      Data & Infrastructure                                ║
║   SQLite (WAL mode) │ Ollama LLM │ Docker Socket │ OpenTelemetry         ║
╚══════════════════════════════════════════════════════════════════════════╝
                              ↕ MCP Protocol (2024-11-05)
╔══════════════════════════════════════════════════════════════════════════╗
║                         KiloCode IDE                                      ║
║   peanut_dispatch_agent · peanut_docker_* · peanut_list_agents           ║
╚══════════════════════════════════════════════════════════════════════════╝

Domain-Driven Design

The gateway follows strict DDD principles with four layers:

Layer	Path	Responsibility
Domain	`src/domain/`	Pure business entities (Agent, User, AuditEntry) with invariant enforcement
Application	`src/application/`	Use cases & services (AuthService, OpenClawService, DockerService, CryptoService)
Infrastructure	`src/infrastructure/`	SQLite repositories, Kilo client, MCP Server
Interface	`src/interfaces/`	Fastify HTTP routes, WebSocket terminal handler

🚀 Quick Start

Prerequisites

Requirement	Version	Notes
Node.js	`≥ 20.0.0`	LTS recommended
pnpm	`≥ 9.0.0`	`npm i -g pnpm`
Docker	Any	Optional, for container management
Python	`≥ 3.10`	Optional, for Python agent
Ollama	Latest	For local LLM inference

Development Setup

# 1. Clone the repository
git clone https://github.com/your-org/peanut-agent.git
cd peanut-agent

# 2. Install all dependencies (monorepo)
pnpm install

# 3. Build shared types package
pnpm --filter @peanut/shared-types build

# 4. Configure environment
cp services/gateway/.env.example services/gateway/.env

# Generate secrets (required)
echo "JWT_SECRET=$(openssl rand -hex 32)"
echo "KILO_ENCRYPTION_KEY=$(openssl rand -hex 32)"
# → Paste these values into services/gateway/.env

# 5. Start the API Gateway (port 3001)
pnpm --filter @peanut/gateway dev

# 6. Start the Dashboard (port 3000) — in a new terminal
pnpm --filter @peanut/dashboard dev

Open http://localhost:3000 and login with:

Email: admin@peanut.local
Password: PeanutAdmin@2024!

Production (Docker Compose)

# 1. Configure secrets
cp .env.example .env
# Edit .env: set JWT_SECRET and KILO_ENCRYPTION_KEY

# 2. Launch all services
docker compose up -d

# Services:
#   Dashboard:  http://localhost:3000
#   Gateway:    http://localhost:3001
#   MCP Server: http://localhost:3001/mcp
#   Ollama:     http://localhost:11434

Install Ollama Models

ollama pull qwen2.5:7b       # Recommended for coding tasks
ollama pull llama3.2:3b      # Lightweight, fast responses
ollama pull codellama:7b     # Code-specialized model
ollama pull nomic-embed-text # For RAG memory embeddings

🔌 KiloCode Integration

Connect KiloCode to PeanutAgent in under 30 seconds.

PeanutAgent v2.0.0 ships a full MCP (Model Context Protocol) Server that KiloCode discovers natively. This gives you free, private AI inference directly inside your IDE.

Step 1 — Add MCP Server to KiloCode

Option A: Via KiloCode UI

Open KiloCode in VS Code
Click the MCP icon in the sidebar
Add Server → Enter URL: http://localhost:3001/mcp

Option B: Edit config directly

Edit ~/.kilo/mcp_settings.json:

{
  "mcpServers": {
    "peanut-agent": {
      "url": "http://localhost:3001/mcp",
      "description": "PeanutAgent Enterprise — Local AI Gateway"
    }
  }
}

Option C: Via Dashboard

Open http://localhost:3000/dashboard/kilocode → copy the pre-configured settings with one click.

Step 2 — Use Local Models from KiloCode

// Discover available local models
peanut_list_agents({ onlineOnly: true })

// Run a coding task on local Ollama — free, private, no API costs
peanut_dispatch_agent({
  message: "Refactor this function to use async/await",
  context: [{ role: "user", content: "Here is the code: ..." }]
})

// Manage Docker containers
peanut_docker_list({ all: false })
peanut_docker_control({ containerId: "my-api", action: "restart" })
peanut_docker_logs({ containerId: "my-api", tail: 50 })

Step 3 — Create a Custom KiloCode Mode (Optional)

{
  "name": "PeanutLocal",
  "slug": "peanut-local",
  "roleDefinition": "You are a local AI assistant powered by PeanutAgent and Ollama. Use peanut_dispatch_agent for all AI tasks — completely free and private.",
  "groups": ["read", "edit", "command"],
  "customInstructions": "Always prefer local Ollama models via peanut_dispatch_agent. Use peanut_list_agents to discover available models. Prefer qwen2.5:7b for coding tasks."
}

Available MCP Tools

Tool	Description	Auth Required
`peanut_dispatch_agent`	Send tasks to local Ollama agents — free, private inference	✗
`peanut_list_agents`	Discover available local AI agents with health status	✗
`peanut_docker_list`	List Docker containers with status and metrics	✗
`peanut_docker_control`	Start, stop, or restart Docker containers	✗
`peanut_docker_logs`	Retrieve container logs for debugging	✗
`peanut_gateway_status`	Check PeanutAgent gateway health and version	✗
`peanut_kilo_complete`	Proxy completions through PeanutAgent to Kilo Code API	✗

MCP Resources

Resource URI	Description
`peanut://agents`	All registered AI agents with health and metrics
`peanut://docker/containers`	Running Docker containers
`peanut://gateway/health`	Gateway health and status
`peanut://audit/recent`	Last 50 audit log entries

Why PeanutAgent + KiloCode?

Scenario	Benefit
Local development	Use Ollama models (qwen2.5, llama3.2) — zero API costs
Privacy-sensitive code	All inference stays on your machine — no data leaks
Docker workflows	Manage containers directly from KiloCode
Hybrid setup	Route simple tasks to local, complex to cloud
Offline work	Full AI coding assistance without internet

📁 Repository Structure

peanut-agent/
├── apps/
│   └── dashboard/                  # Next.js 15 Admin Dashboard
│       ├── src/app/
│       │   ├── auth/login/         # Authentication page
│       │   └── dashboard/
│       │       ├── kilocode/       # 🆕 KiloCode MCP integration page
│       │       ├── agents/         # Agent management
│       │       ├── docker/         # Docker management
│       │       ├── audit/          # Immutable audit log viewer
│       │       ├── terminal/       # WebSocket terminal
│       │       └── settings/       # Platform settings
│       ├── src/components/         # Reusable UI components (Radix UI)
│       └── src/lib/                # API client, auth utilities
│
├── services/
│   └── gateway/                    # Fastify API Gateway (TypeScript, DDD)
│       ├── src/domain/             # Business entities (Agent, User, AuditEntry)
│       ├── src/application/        # Services (Auth, OpenClaw, Docker, Crypto)
│       ├── src/infrastructure/     # SQLite repos, Kilo client, MCP server
│       └── src/interfaces/         # HTTP routes, WebSocket handler
│
├── packages/
│   └── shared-types/               # Shared TypeScript interfaces (incl. MCP types)
│
├── docs/                           # Documentation
│   ├── ARCHITECTURE.md
│   ├── KILOCODE_INTEGRATION.md
│   ├── REFLECTION_MEMORY.md
│   ├── SECURITY.md
│   ├── TROUBLESHOOTING.md
│   └── WIZARD.md
│
├── agent.py                        # Python AI agent core (local LLM)
├── tools.py                        # Secure tool executor (allowlist-based)
├── memory.py                       # RAG memory system (JSONL + embeddings)
├── reflection.py                   # Reflection loop (auto-correction)
├── gateway.py                      # Console gateway (multi-session)
├── web_ui.py                       # Web gateway (FastAPI + WebSocket)
├── docker-compose.yml              # Production deployment
└── .github/workflows/              # CI/CD pipelines

🔒 Security Architecture

Authentication Stack

┌─────────────────────────────────────────────────────┐
│  Login Flow                                          │
│  ─────────────────────────────────────────────────  │
│  1. POST /auth/login → scrypt verify → JWT issue    │
│  2. POST /auth/totp/verify → TOTP check → session   │
│  3. httpOnly + Secure + SameSite=Strict cookie       │
│  4. 8-hour session expiry, revokable in SQLite       │
└─────────────────────────────────────────────────────┘

Feature	Implementation
JWT Sessions	httpOnly, Secure, SameSite=Strict cookies · 8h expiry
TOTP 2FA	RFC 6238 via `otplib` · 10 single-use backup codes
Password Hashing	scrypt (N=2¹⁴, r=8, p=1) · 64-byte output · 32-byte random salt
Secret Encryption	AES-256-GCM · keys stored in env, never in DB
Security Headers	`@fastify/helmet` · HSTS, CSP, X-Frame-Options

Immutable Audit Chain

Every action is recorded in a cryptographic fingerprint chain:

Entry N:  SHA-256(previousFingerprint + content) → fingerprint
Entry N+1: SHA-256(fingerprint_N + content) → fingerprint

Any modification to any entry breaks the chain — tamper detection is automatic.

Adaptive Rate Limiting

Scope	Limit	Backoff
Login (per IP)	10 req/min	Exponential up to 5 min
TOTP (per user)	5 attempts/min	Exponential up to 10 min
API Dispatch (per user)	60 req/min	Standard

⚙️ OpenClaw Orchestrator

The OpenClaw service implements Smooth Weighted Round-Robin (Nginx algorithm) for intelligent load balancing:

Agents: [{name: A, weight: 5}, {name: B, weight: 3}, {name: C, weight: 2}]

Each request:
  1. Increment currentWeight by agent.weight for all agents
  2. Select agent with highest currentWeight
  3. Subtract totalWeight from selected agent's currentWeight

Result: ~50% → A, ~30% → B, ~20% → C (proportional to weights)

Features:

Dynamic agent registration/deregistration at runtime
Health-based routing — unhealthy agents automatically excluded
Per-agent metrics: latency, success rate, token usage
Background health checks every 30 seconds

📡 API Reference

Authentication

POST /api/v1/auth/login              Login (email + password)
POST /api/v1/auth/totp/verify        Complete TOTP 2FA verification
POST /api/v1/auth/logout             Invalidate session
GET  /api/v1/auth/me                 Get current user profile
POST /api/v1/auth/totp/setup         Enable 2FA (returns QR code)
POST /api/v1/auth/password           Change password

Agent Management

GET    /api/v1/agents                List all agents with health status
POST   /api/v1/agents                Register new agent
PUT    /api/v1/agents/:id            Update agent configuration
DELETE /api/v1/agents/:id            Remove agent
GET    /api/v1/agents/:id/health     Force health check
POST   /api/v1/openclaw/dispatch     Send request (auto load-balanced)

Docker Management

GET    /api/v1/docker/containers              List containers
POST   /api/v1/docker/containers              Deploy new container
POST   /api/v1/docker/containers/:id/start   Start container
POST   /api/v1/docker/containers/:id/stop    Stop container
DELETE /api/v1/docker/containers/:id         Remove container
GET    /api/v1/docker/containers/:id/metrics Real-time metrics
GET    /api/v1/docker/containers/:id/logs    Container logs
GET    /api/v1/docker/images                 List local images

Kilo Code Bridge

GET  /api/v1/kilo/status     Connection status + usage stats
GET  /api/v1/kilo/config     Configuration (admin only)
PUT  /api/v1/kilo/config     Update config + API key (AES-256 encrypted)
POST /api/v1/kilo/complete   Proxy completion request to Kilo Code API
GET  /api/v1/kilo/usage      Token usage statistics

MCP Server (v2.0.0)

GET  /mcp                    MCP server discovery (capabilities, tools, resources)
POST /mcp                    JSON-RPC 2.0 endpoint (all MCP methods)
GET  /mcp/events             SSE endpoint for real-time updates

Supported JSON-RPC methods: initialize, tools/list, tools/call, resources/list, resources/read, prompts/list, prompts/get, ping

WebSocket Terminal

ws://localhost:3001/ws/terminal    Authenticated real-time terminal

🧪 Testing

# Run all tests (monorepo)
pnpm test

# Gateway unit tests
pnpm --filter @peanut/gateway test

# Gateway with coverage report
pnpm --filter @peanut/gateway test:coverage

# Run specific test file (e.g., MCP server)
cd services/gateway && pnpm vitest run tests/unit/mcp.server.test.ts

# Dashboard tests
pnpm --filter @peanut/dashboard test

# Python agent tests
pytest tests/ -v

# Python with coverage
pytest tests/ -v --cov=. --cov-report=html

Coverage requirements: 80% lines · functions · branches · statements

🌍 Environment Variables

Gateway (`services/gateway/.env`)

Variable	Required	Default	Description
`JWT_SECRET`	✅	—	JWT signing secret (min 32 chars)
`KILO_ENCRYPTION_KEY`	✅	—	AES-256 key for secrets (64 hex chars)
`PORT`	✗	`3001`	Gateway HTTP port
`CORS_ORIGIN`	✗	`http://localhost:3000`	Allowed CORS origins
`DATA_DIR`	✗	`./data`	SQLite database directory
`LOG_LEVEL`	✗	`info`	Pino log level
`DEFAULT_ADMIN_PASSWORD`	✗	—	Override initial admin password

Dashboard (`apps/dashboard/.env.local`)

Variable	Required	Default	Description
`NEXT_PUBLIC_API_URL`	✗	`http://localhost:3001`	Gateway HTTP URL
`NEXT_PUBLIC_WS_URL`	✗	`ws://localhost:3001`	Gateway WebSocket URL
`GATEWAY_URL`	✗	—	Internal gateway URL for Next.js rewrites

🐍 Python Agent (Legacy)

The original Python agent runs independently and provides a lightweight local AI interface:

# Interactive setup wizard
python wizard.py

# Console gateway (multi-session, Rich UI)
python gateway.py

# Web gateway (FastAPI + WebSocket)
python web_ui.py
# Open: http://127.0.0.1:18889/

Python agent features:

🔄 Reflection Loop — Auto-correction with Pydantic schema validation (up to 3 retries)
🧠 RAG Memory — JSONL append-only store with Ollama embeddings + cosine similarity
🛡️ Allowlist Security — Shell commands restricted to safe read/diagnostic operations
🎮 Gamification — Peanut counter system (~/.peanut-agent/state.json)

📦 Tech Stack

Layer	Technology	Version	Purpose
Backend	Fastify	4.x	High-performance HTTP server
	TypeScript	5.7	Type safety across the stack
	better-sqlite3	11.x	Embedded database (WAL mode)
	@fastify/jwt	8.x	JWT authentication
	otplib	12.x	TOTP 2FA (RFC 6238)
	Zod	3.x	Runtime schema validation
Frontend	Next.js	15.1	React framework (App Router)
	React	19.x	UI library
	Radix UI	Latest	Accessible component primitives
	Tailwind CSS	3.x	Utility-first styling
	Recharts	2.x	Real-time metrics charts
AI/ML	Ollama	Latest	Local LLM inference
	MCP Protocol	2024-11-05	KiloCode tool integration
	OpenTelemetry	1.x	Distributed tracing
Testing	Vitest	3.x	TypeScript unit/integration tests
	pytest	Latest	Python agent tests
	@testing-library/react	16.x	Dashboard component tests

🤝 Contributing

Contributions are welcome! Please read CONTRIBUTING.md for:

Development workflow and branch strategy
Code style guidelines (ESLint + TypeScript strict mode)
Test requirements (80% coverage threshold)
PR review process

📄 License

MIT — see LICENSE for details.

Built with ❤️ for the KiloCode community

⭐ Star on GitHub · 🐛 Report Bug · 💡 Request Feature

_{PeanutAgent Enterprise v2.0.0 · MIT License · Local-First AI}

Name		Name	Last commit message	Last commit date
Latest commit History 37 Commits
.github/workflows		.github/workflows
agentlow		agentlow
apps/dashboard		apps/dashboard
assets		assets
docs		docs
integrations		integrations
packages/shared-types		packages/shared-types
scripts		scripts
services/gateway		services/gateway
src/agentlow		src/agentlow
tests		tests
web		web
.env.example		.env.example
.gitignore		.gitignore
.npmrc		.npmrc
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
EXECUTIVE_SUMMARY.md		EXECUTIVE_SUMMARY.md
LICENSE		LICENSE
QUICKSTART.md		QUICKSTART.md
README.es.md		README.es.md
README.md		README.md
agent.py		agent.py
ci.yml		ci.yml
config.py		config.py
docker-compose.yml		docker-compose.yml
examples.py		examples.py
gateway.py		gateway.py
init.py		init.py
install.ps1		install.ps1
install.sh		install.sh
memory.py		memory.py
package.json		package.json
peanut.py		peanut.py
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
pytest.ini		pytest.ini
reflection.py		reflection.py
requirements.txt		requirements.txt
run_gateway.ps1		run_gateway.ps1
run_web.ps1		run_web.ps1
setup.py		setup.py
test_agent.py		test_agent.py
test_memory.py		test_memory.py
test_reflection.py		test_reflection.py
tools.py		tools.py
tsconfig.base.json		tsconfig.base.json
web_ui.py		web_ui.py
wizard.py		wizard.py

License

smouj/peanut-agent

Folders and files

Latest commit

History

Repository files navigation

✨ What is PeanutAgent?

🔌 MCP Server (v2.0.0)

🤖 Local AI Backend

🐳 Docker Management

🔒 Enterprise Security

📊 Admin Dashboard

⚖️ Smart Load Balancing

📸 Dashboard Screenshots

🖥️ Main Dashboard

🔐 Login Page

📊 Dashboard Overview (1440px)

🏗️ Architecture

Domain-Driven Design

🚀 Quick Start

Prerequisites

Development Setup

Production (Docker Compose)

Install Ollama Models

🔌 KiloCode Integration

Step 1 — Add MCP Server to KiloCode

Step 2 — Use Local Models from KiloCode

Step 3 — Create a Custom KiloCode Mode (Optional)

Available MCP Tools

MCP Resources

Why PeanutAgent + KiloCode?

📁 Repository Structure

🔒 Security Architecture

Authentication Stack

Immutable Audit Chain

Adaptive Rate Limiting

⚙️ OpenClaw Orchestrator

📡 API Reference

🧪 Testing

🌍 Environment Variables

Gateway (services/gateway/.env)

Dashboard (apps/dashboard/.env.local)

🐍 Python Agent (Legacy)

📦 Tech Stack

🤝 Contributing

📄 License

About

Resources

License

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Gateway (`services/gateway/.env`)

Dashboard (`apps/dashboard/.env.local`)

Packages