Private, compounding R&D reasoning engine.
Runs entirely on your hardware. No cloud. No external memory. No vendor dependencies.
RadBot is a local AI agent architecture designed for research and development work. It combines a local LLM with a network of specialized MCP containers, a compounding knowledge base, and cross-layer causal reasoning. RadBot is lightweight and runs on a mid-range machine with single-command deployment.
Beta notice: RadBot v0.1.0-beta is functional and architecturally stable. Cross-domain R&D validation is ongoing. Expect rough edges; report them via GitHub Issues.
R&D capability has historically required expensive infrastructure, teams, and institutional access. RadBot is designed to virtualize R&D infrastructure.
The architecture is designed for efficiency:
- The model never touches the internet directly
- All external calls go through controlled containers
- The knowledge base compounds across sessions and projects
- Background workers continuously improve retrieval quality
- RadBot does the heavy lifting, not your hardware
git clone https://github.com/pablo-chacon/RadBot
cd RadBot
# 1. Configure environment
cp .env.example .env
# Edit .env — at minimum set:
# POSTGRES_PASSWORD (must change from default)
# SEARXNG_SECRET_KEY (run: openssl rand -hex 32)
# 2. Deploy
.deploy.shOpen http://localhost:7860
The deploy script runs scripts/check_env.sh automatically and will refuse to start if unsafe defaults are detected. See Configuration for all options.
CPU-only (no GPU):
./deploy.sh --cpuTear down:
./deploy.sh --down # stop containers, keep data
./deploy.sh --reset # stop containers, DESTROY data╔══════════════════════════════════════════════════════════════════════╗
║ HOST MACHINE ║
║ ║
║ ┌─────────────────────────────────────────────────────────────┐ ║
║ │ radbot-internal network │ ║
║ │ (no external routing) │ ║
║ │ │ ║
║ │ ┌──────────┐ ┌─────────────────────────────────────┐ │ ║
║ │ │ Ollama │◄────│ Orchestrator │ │ ║
║ │ │ :11434 │ │ (model + UI :7860) │ │ ║
║ │ └──────────┘ └──────────────┬──────────────────────┘ │ ║
║ │ │ │ ║
║ │ ┌────────────────────┼────────────────────┐ │ ║
║ │ │ │ │ │ ║
║ │ ┌─────▼──────┐ ┌───────▼──────┐ ┌────────▼───┐ │ ║
║ │ │ mcp-memory │ │ Processing │ │ Synthesis │ │ ║
║ │ │ (DB layer) │ │ Lanes │ │ │ │ ║
║ │ └─────┬──────┘ └───────┬──────┘ └────────────┘ │ ║
║ │ │ │ │ ║
║ │ ┌─────▼──────┐ ┌───────▼──────────────────────┐ │ ║
║ │ │ PostgreSQL │ │ mcp-search │ mcp-fetch │ │ ║
║ │ │ + pgvector │ │ mcp-text │ mcp-struct │ │ ║
║ │ └────────────┘ │ mcp-geo │ mcp-code │ │ ║
║ │ └──────┬───────────────────────┘ │ ║
║ └─────────────────────────────────┼─────────────────────────┘ ║
║ │ ║
║ ┌─────────────────────────────────▼─────────────────────────┐ ║
║ │ radbot-egress network │ ║
║ │ (mcp-search and mcp-fetch only) │ ║
║ └─────────────────────────────────┬─────────────────────────┘ ║
║ │ ║
╚════════════════════════════════════╪═══════════════════════════════╝
│
Internet
(allowlisted only)
User prompt
│
▼
┌─────────────────┐
│ Orchestrator │ ← sole user-facing interface
│ (model layer) │
└────────┬────────┘
│ determines relevant lanes
▼
┌────────────────────────────────────────────────┐
│ Parallel Processing │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │mcp-search│ │mcp-fetch │ │mcp-text │ ... │
│ │ (DDG) │ │+ process │ │ │ │
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ │
│ │ │ │ │
└───────┼─────────────┼─────────────┼────────────┘
│ │ │
└─────────────┼─────────────┘
│
▼
┌─────────────────┐
│ Synthesis │ ← computes inter-lane agreement
│ │ flags conflicts
│ C1 + C2 = P │ produces confidence score
└────────┬────────┘
│
▼
┌─────────────────┐
│ Orchestrator │ ← model resolves conflicts
│ (reasoning) │ derives conclusions
└────────┬────────┘
│
┌───────────┼───────────┐
▼ ▼ ▼
store chunks store check principle
+ embeddings conclusion candidates
│ │ │
└───────────┼───────────┘
▼
mcp-memory
(pgvector)
│
▼
Response to user
Session
│
┌───────────┴───────────┐
▼ ▼
Retrieve project Retrieve principles
conclusions (cross-project)
│ │
└───────────┬───────────┘
│
Grounded context
│
▼
Model reasoning
│
New conclusions
│
┌────────────┼────────────┐
▼ ▼ ▼
Store in Record Flag principle
project DB chunk usage candidate?
│
▼ if N projects confirm
XGBoost ──────────────────────►
reranker Principles table
updates │
▼
Injected into system
prompt next session
┌─────────────────────────────────────────────────────┐
│ radbot-internal (Docker bridge, internal: true) │
│ │
│ postgres ollama mcp-memory orchestrator │
│ mcp-text mcp-struct mcp-geo mcp-code │
│ synthesis │
│ │
│ ┌──────────────────────────────────────────────┐ │
│ │ Also on radbot-egress (internet access): │ │
│ │ │ │
│ │ searxng mcp-search mcp-fetch │ │
│ └──────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────┘
│
Internet
The model has no direct internet access. Every external call is containerized, auditable.
projects
└── sessions
├── pages
│ └── chunks (embedded, flagged, reranked)
├── conclusions (confidence-rated, supersedable)
└── query_lanes (synthesis audit trail)
principle_candidates <- promoted when confirmed across N projects
principles <- injected into system prompt at session start
reranker_samples <- XGBoost training data (chunk usage feedback)
| Level | Meaning |
|---|---|
speculative |
Logical but no evidence yet |
plausible |
Consistent with known evidence, not yet tested |
supported |
Evidence exists, causal chain is coherent |
verified |
Tested, reproducible, chain confirmed |
Project A conclusion ──┐
Project B conclusion ──┼──► principle_candidates ──► principles table
Project C conclusion ──┘ (when threshold met) (injected at runtime)
Principles are cross-project patterns that the system has confirmed independently across multiple research domains. They carry higher weight in reasoning than single-project conclusions.
Every container follows same design pattern. Follow the design pattern to add new processing lane.
MCP Container
├── Inherits RadBotMCPServer base class
├── Declares tools: READ | WRITE | OPERATE
├── Never exposes raw SQL or DB structure
├── Logs every call: project_id + session_id + call_id
└── Raises RadBotError — DB exceptions never reach the model
class YourServer(RadBotMCPServer):
def _register_tools(self):
return [{
"name": "your_tool",
"description": "What this does. Model reads this.",
"parameters": {"query": "string"},
"handler": self.your_tool,
}]
def your_tool(self, query, context=None):
return do_your_thing(query)./deploy.sh # default: phase 1, GPU
./deploy.sh --phase 2 # add processing lanes
./deploy.sh --no-gpu # CPU-only mode
./deploy.sh --phase 1 --no-gpu # CPU-only, phase 1| Phase | Services added | What you get |
|---|---|---|
| 1 | search, fetch, memory | Core loop — search, store, reason |
| 2 | mcp-text, mcp-struct | NLP and structured data lanes |
| 3 | synthesis | Parallel lane confidence scoring |
| 4 | mcp-geo, mcp-code | Geospatial and code analysis |
| 5 | XGBoost reranker | Self-improving retrieval |
./deploy.sh --down # stop containers, keep data
./deploy.sh --reset # stop + delete all knowledge base data| Tier | GPU VRAM | System RAM | Storage | Model | Response time |
|---|---|---|---|---|---|
| Minimum | 8GB | 16GB | 256GB SSD | Qwen3-14B Q4 | 30–60s |
| Recommended | 16–24GB | 32GB | 512GB NVMe | Qwen3-30B-A3B Q4 | 8–20s |
| Over-recommended | 24GB+ | 64GB | 1TB NVMe | Qwen3-30B Q8 | 4–10s |
| CPU-only | — | 64GB | 512GB NVMe | Qwen3-14B Q4 | 2–5 min |
The recommended tier runs Qwen3-30B-A3B — a Mixture of Experts model that activates ~3B parameters per token while reasoning at 30B depth. Efficient by model architecture, on top of an efficient system architecture.
RadBot runs anywhere Docker runs. Same deploy.sh everywhere.
Local machine -> fully private, zero cost
Home server -> always-on, LAN accessible via hostname
VPS (Hetzner, etc.) -> accessible anywhere, your instance
On-prem server -> team deployment, shared knowledge base
Tailscale (recommended) zero-config private network, no open ports
Nginx + Caddy reverse proxy with automatic TLS
Direct bind 0.0.0.0:7860 on trusted network
Ollama exposes a full OpenAI-compatible API at :11434/v1.
Any editor or tool that accepts a custom OpenAI endpoint works:
// VSCode / Copilot (or preferably Continue.dev)
{
"openaiBaseUrl": "http://localhost:11434/v1"
}Continue.dev is the recommended choice over Copilot for local model integration built for this use case, Ollama-native, nothing routed externally.
All behavior is controlled via .env. Copy from config/.env.example:
# Model
OLLAMA_MODEL=qwen3:30b-a3b
# Database
POSTGRES_PASSWORD=your_password_here
# Tuning
RERANKER_COLD_START_SESSIONS=5 # sessions before XGBoost activates
PRINCIPLE_MIN_PROJECTS=2 # projects needed to promote a principle
SYNTHESIS_AGREEMENT_THRESHOLD=0.6 # below this, conflict flagged for modelradbot/
├── deploy.sh <- single entry point
├── config/
│ └── .env.example
├── docker-compose.yml
├── containers/
│ ├── shared/ <- base class, DB, models, exceptions
│ ├── mcp-memory/ <- sole DB access layer
│ ├── processing/
│ ├── searxng/ <- self-hosted meta-search (Google/Bing/DDG/arXiv)
│ ├── processing/
│ │ ├── mcp-search/ <- SearXNG primary, DDG fallback
│ │ ├── mcp-fetch/ <- retrieval + transparent processing
│ │ ├── mcp-text/ <- NLP lane
│ │ ├── mcp-struct/ <- structured data lane
│ │ ├── mcp-geo/ <- geospatial lane
│ │ └── mcp-code/ <- code analysis lane
│ ├── synthesis/ <- lane result combiner
│ └── orchestrator/ <- UI + agent loop
├── db/
│ └── init/ <- schema, indexes, seed (auto-runs on boot)
├── volumes/ <- gitignored, persisted data
└── docs/
├── architecture.md
└── MANIFESTO.md
Privacy by topology: the model is air-gapped from the internet. External access is containerized and auditable. No policy required.
Efficiency by architecture: parallel processing lanes, MoE model selection, two-stage retrieval (pgvector -> XGBoost reranker). The system is lightweight not by cutting capability but by designing each layer to do exactly its job.
Compounding knowledge: conclusions build on conclusions. Patterns verified across projects become principles. Principles feed future reasoning. The system gets more capable the more it's used.
Extensible by design: every MCP container follows the same pattern. Adding a new processing lane requires no understanding of the full system. The base class handles logging, error handling, and DB access uniformly.
No single point of dependency: containers restart independently. The model stays up. Data outlives containers. No component's failure takes down the system.
RadBot is an open-source software tool provided for research, educational, and personal productivity purposes. Use of RadBot is entirely at your own risk.
RadBot is provided "as is", without warranty of any kind, express or implied, including but not limited to warranties of merchantability, fitness for a particular purpose, accuracy, reliability, or non-infringement. The author(s) make no representations regarding the correctness, completeness, or suitability of any output produced by RadBot or any AI model it interfaces with.
RadBot interfaces with large language models (LLMs) that may produce outputs that are inaccurate, incomplete, misleading, biased, or otherwise unreliable. No output from RadBot constitutes professional advice of any kind including but not limited to legal, medical, financial, scientific, engineering, or regulatory advice. Any output used as a basis for real-world decisions is used entirely at the operator's discretion and risk.
The person deploying and operating RadBot ("the Operator") is solely responsible for:
- Ensuring compliance with all applicable local, national, and international laws and regulations in their jurisdiction
- All data processed through RadBot, including personally identifiable information, proprietary data, or regulated content
- Any AI model(s) loaded into or accessed by RadBot, including compliance with the terms of use and licenses of those models
- Any outputs generated by RadBot and how those outputs are used, shared, or acted upon
- Ensuring RadBot is not used for any unlawful, harmful, deceptive, or abusive purpose
The Operator is responsible for any use of RadBot by third parties granted access to the Operator's deployment. The author(s) accept no responsibility for use by parties other than the individual who originally deployed the software.
To the maximum extent permitted by applicable law, in no event shall the author(s), contributors, or copyright holders be liable for any claim, damages, or other liability — whether in an action of contract, tort, or otherwise arising from, out of, or in connection with RadBot or the use or other dealings in RadBot. This includes but is not limited to direct, indirect, incidental, special, exemplary, consequential, or punitive damages, loss of data, loss of revenue, or any harm resulting from reliance on AI-generated outputs.
If you modify, extend, or distribute RadBot or any derivative work, you assume full responsibility for the modified software and its use. The author(s) of the original work bear no responsibility for any modifications made by third parties.
MIT