joshbot
A nanobot-class personal AI agent as a single ~19MB Go binary — no Python, no venv, no runtime dependencies. Self-hosted, curl to running in under a minute, and scriptable enough to test in CI. Self-learning memory, skill self-creation, subagent delegation, multi-provider LLM routing, and Telegram/Discord chat all ship in the one static binary.
Why joshbot instead of a Python agent stack?
| joshbot | Typical Python agent (e.g. nanobot) |
|---|
| Install | curl … | bash → one binary | pip/venv, interpreter + wheels to keep in sync |
| Runtime deps | Zero — static Go binary (~19MB) | CPython + a dependency tree |
| Startup | No interpreter, no imports — the binary is the runtime | Interpreter + import cost |
| Shell safety | Deny-listed and env-stripped (no API keys inherited), optional OS sandbox | Varies |
| Untrusted skills | Inert until joshbot skills trust, bound to a directory-tree hash | Varies |
| Scriptability | Every command non-interactive; --output-format json, exit-code contract | Varies |
joshbot is heavier on guarantees, lighter on your machine.
Features
- Self-Learning Memory - Automatically remembers important facts across conversations using a structured fact system (categorized with SHA256-based IDs, confidence scoring, source tracking, and deduplication)
- Context Compression - Summarizes old context to stay within token limits; works well with small local models
- Skill Self-Creation - Creates new capabilities for itself as markdown files, with auto-detection from conversation patterns and LLM-based extraction
- Subagent Delegation - Spawns focused subagents for complex multi-step tasks
- Browser chat UI - optional, off by default: set
api.webui to true and joshbot serve also serves a self-contained dark-mode chat page at /, embedded in the binary, behind a cookie login that exchanges an api.api_keys value for a session
- OpenAI-Compatible API -
joshbot serve exposes the agent at /v1/chat/completions (streaming included) and /v1/models, plus /v1/audio/transcriptions when stt is configured and /v1/embeddings when embeddings is configured, so any OpenAI client can drive it; authentication is mandatory and it binds loopback by default
- Telegram & Discord - Chat from your phone with full media support; both fail closed on an empty allowlist
- Scriptable / Non-Interactive - Every command runs headless;
agent -m for one-shot, --output-format json/stream-json for machine-readable output, --resume to thread sessions, and a stable exit-code contract for CI
- Interactive CLI - Rich terminal interface with markdown rendering
- Multi-Provider LLM - OpenRouter, Anthropic, OpenAI, Groq, Poolside, DeepSeek, Gemini, NVIDIA, and more
- Named Profiles - Switch model, provider and endpoint per run with
--profile; profiles hold a credential's variable name, never the credential
- Model-Centric Config - Simplified model configuration with provider auto-detection and fallback chains
- Prompt Caching - Intelligent caching of system prompts with mtime-based invalidation for faster responses
- Tool Use - File operations, shell commands, web search, scheduling, and more
- Resilient Web Search - /// fall back exa-cli → Exa MCP → DuckDuckGo, each leg on its own deadline so one slow call can't eat the whole turn; an optional tuner (, off by default) learns per-tool timeouts from real timeout/success history and persists the adjustment across restarts
Requirements
- Go 1.25+ (for building from source)
- An LLM API key — NVIDIA NIM's free tier works, no credit card needed (the onboarding wizard defaults to it); OpenRouter also has a free tier
- Linux or macOS recommended
Quick Start
One-Line Install (Recommended)
curl -fsSL https://raw.githubusercontent.com/bigknoxy/joshbot/main/install.sh | bash
Downloads the latest binary release for your platform. Supports Linux and macOS (amd64/arm64).
For specific versions:
curl -fsSL https://raw.githubusercontent.com/bigknoxy/joshbot/main/install.sh | bash -s -- -v v1.0.0
Install with Go
go install github.com/bigknoxy/joshbot/cmd/joshbot@latest
Ensure $GOPATH/bin or $HOME/go/bin is in your PATH.
Build from Source
git clone https://github.com/bigknoxy/joshbot.git
cd joshbot
go build -o joshbot ./cmd/joshbot
Docker
docker build -t joshbot .
docker run -it -v ~/.joshbot:/home/joshbot/.joshbot joshbot onboard
This is the beginning of the README. Read the rest at the original. Read the full README ↗
