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

여기까지가 README 앞부분입니다. 나머지는 원문에서 읽을 수 있습니다. README 전문 보기 ↗