README.md

---
license: mit
tags:
  - hermes
  - ai-agent
  - ollama
  - docker
  - auto-discovery
  - local-ai
  - mcp
  - portable
  - self-hosted
  - tabbyapi
  - vllm
library_name: docker
---

# 🏕️ Basecamp — The First Portable AI Agent Container with Network Auto-Discovery

**v1.0.6** — the adaptive release (current):
- **Adaptive discovery** — boot ALWAYS rescans (stale config can't freeze
  it), subnet sweep finds services when no docker socket is mounted,
  `BASECAMP_EXTRA_HOSTS` reaches cross-host/remote machines, network name
  is irrelevant.
- **Any mess, any fix** — all 44 fix recipes inline in the agent's skill
  (not just discovered services); `tavern status` lists EVERY service
  with link:port; the SOUL answers service questions from tavern status.
- **Auto-wire** — a webui-only network gets basecamp's bundled Ollama
  wired as the engine automatically, the user is told exactly what
  happened, and given cloud options (Nous portal ~$20/mo, Ollama.com,
  OpenRouter).

**v1.0.5** — the self-healing release:
- **The Fixer's toolbox** — basecamp now ships with every CLI it needs to
  EXECUTE fixes: postgres/mongosh/sqlite/redis clients, docker CLI +
  compose, yq, and full network diagnostics. It doesn't just describe the
  fix — it can run it (when the docker socket is mounted).
- **`tavern self-check`** — verifies every discovered service against its
  recipe and reports ✅/⚠️/❌ (self-heal #1). "The fixer approves."
- **`tavern update-check`** — polls Docker Hub/GHCR for newer image tags
  and reports what moved (self-heal #2).
- **CI pitfall testing** — GitHub Actions boots the full coding pack in
  the cloud on every push + nightly, runs self-check, and fails loudly on
  recipe drift (self-heal #3).
- **Coding starter pack** — 12 services incl. postgres/pgvector memory +
  mongo, with all verified pitfalls baked into the recipes (tabby pin,
  flowise pin, librechat mongo requirement, GHCR locations).

**v1.0.4** — the fixer release. Basecamp Hermes now carries a soul:
- **The Fixer** — Basecamp Hermes has a purpose: making stacks talk to
  themselves. The SOUL.md gives it identity and a Fixer's Creed (name the
  setting, give the one line, verify it) so it answers connection problems
  with conviction, not guesses.
- **Fix recipes baked in** — 39 per-service wiring recipes (config location,
  exact keys, one-line fix, verification) ship inside the container. The
  stack skill embeds recipes inline for everything discovered, plus a full
  `references/wiring-recipes.md` for the rest.
- **Skill always at hand** — SOUL.md + `-s basecamp-stack` preload on every
  hermes launch mean the agent has the stack knowledge without having to
  remember to look for it.

**v1.0.3** — the identity + reliability release:
- **Indigo identity** — Basecamp runs its own indigo skin ("Welcome to Basecamp
  Hermes!") so you can tell it apart from a host install at a glance; model
  readout shows `basecamp/<model>` (created via `ollama cp` alias on the
  discovered engine).
- **Boot race fixed** — the bundled-model pull now starts AFTER discovery,
  so the network scan never competes with a multi-GB download. Cold boots
  consistently discover the whole stack (7/7 on the reference stack).
- **Smarter auto-select** — an external Ollama (your stack) is preferred
  over the bundled fallback; alias creation is verified before use, and
  stale `basecamp/` aliases are excluded from model lists.
- **Separate commands** — host `hermes` = your install; `basecamp` =
  the container edition. No more ambiguity about which agent you're in.
- **`tavern wire` wiring wizard** — every boot runs a stack wiring audit
  (✅ wired / ⚠️ needs attention / ❌ broken) with the exact one-line fix
  for anything mis-wired. Ask the container's Hermes "why won't my stack
  talk to each other?" — it has the ground truth via the injected
  `basecamp-stack` skill.
- **Expanded discovery** — 30+ service probes: KoboldCpp, LM Studio, SGLang,
  llamafile, exo, TGI, Aphrodite, LibreChat, LobeChat, AnythingLLM, Dify,
  Flowise, n8n, Langflow, RAGFlow, Qdrant, Milvus, Chroma, Weaviate,
  ComfyUI, A1111, InvokeAI, Whisper, Piper, OpenRouter, KoboldAI Horde.

**v1.0.2** — the stack-gauntlet release (tested against a live 6-service AI
stack):
- **TabbyAPI + SillyTavern now discovered** — auth-gated services (401/403)
  are fingerprinted and listed as `[needs auth]` so the connect screen can
  prompt for keys (previously invisible)
- **Fixed hermes v0.20 wiring** — named custom provider (`providers.basecamp`)
  with inline API key, sidestepping the #28660 security gate that blocks env
  keys for LAN endpoints; reasoning-effort turned off (local engines reject
  thinking params with HTTP 400); stale context probes cleared
- **Ollama preferred for auto-select** — hermes hard-requires ≥64K context, so
  headless mode picks an Ollama endpoint; OpenAI-compatible engines (TabbyAPI,
  vLLM) are still listed for interactive choice
- **SearXNG probed via its fast static page** — no more slow search-query probe
  losing the boot race

**v1.0.1** — rebuilt on the official Hermes installer (the old `pip3 install
hermes-cli` stub is gone), leaked-key fallback removed from `tavern.sh`, and
the git history scrubbed of both. Build from source below.

One image. One command. It finds your AI stack and just works.

Basecamp bundles **Hermes Agent** (the full agent — tools, skills, memory,
gateway) **+ Ollama** (a brain it always has in its backpack), then does
something nobody else's container does: **it sniffs your network on first
boot** and auto-discovers your entire local AI stack — Ollama, TabbyAPI,
vLLM, LiteLLM, LocalAI, llama.cpp, SearXNG, MCPO, Open WebUI, SillyTavern —
and connects Hermes to the best brain it finds. No hardcoded URLs. No config
files to hand-edit. Just `docker run`.

## Self-healing (the fixer maintains itself)

Basecamp ships three self-healing layers so its wiring knowledge stays
true even as the ecosystem moves:

1. **`tavern self-check`** — runs every discovered service against its
   recipe's verification step and reports ✅/⚠️/❌. Catches stale recipes
   and broken services before a user hits them. "The fixer approves."
2. **`tavern update-check`** — polls Docker Hub / GHCR for the newest
   published tag of every discovered service and reports what moved, so
   you can pull the newer image before an old one rots.
3. **CI pitfall testing** (`.github/workflows/recipe-verify.yml`) — on
   every push and nightly, GitHub Actions boots the full coding starter
   pack in the cloud, runs `tavern self-check`, and fails loudly when a
   recipe has gone stale (an image moved, a flag changed, a service
   renamed). Recipe drift gets caught in CI, not on a user's box.

## The Coding Starter Pack (10 best-of-breed AI coding tools)

Basecamp ships a companion compose file that stands up a complete AI coding
environment — every tool in its own container, all on the same Docker
network, all wired to your stack's Ollama + TabbyAPI, all able to call each
other by container name.

```bash
cd basecamp
docker compose -f docker-compose.starter.yml up -d
basecamp rediscover     # basecamp finds the whole pack
basecamp wire           # wiring audit
```

| # | Service | What it is | Port |
|---|---------|-----------|------|
| 1 | **code-server** | VS Code in the browser (the IDE) | 8443 |
| 2 | **qdrant** | Vector DB — code RAG backbone | 6333 |
| 3 | **chroma** | Lightweight vector DB (alternative) | 8005 |
| 4 | **n8n** | Workflow automation | 5678 |
| 5 | **lobe-chat** | AI chat UI (wired to stack Ollama) | 3210 |
| 6 | **anythingllm** | RAG workspace (docs + codebase Q&A) | 3001 |
| 7 | **librechat** | Multi-model chat UI (needs mongo — included) | 3080 |
| 8 | **meilisearch** | Full-text search (code/docs search) | 7700 |
| 9 | **postgres** | Postgres + pgvector — Hermes long-term memory | 5432 |
| 10 | **mongo** | MongoDB — LibreChat's database | 27017 |

**Removed (verified broken, 2026-08-09):** `tabby` (its bundled llama-server
dlopens libcuda.so.1 even with `--device cpu` — crash-loops in CPU-only
containers; needs GPU access) and `flowise` (upstream dependency bug —
`@langchain/core` export error crashes boot on `latest` and 3.1.4).
Both have full "do not use" recipes in basecamp so the agent warns before
anyone ships them again.

The IDE comes pre-loaded with **Continue.dev** (AI assistant). Point
Continue's model at `http://ollama:11434/v1` (or
`http://tabbyapi:5000/v1`) — your stack's models power the whole pack.
(Inline code completion via the Tabby extension is available but needs a
completion server; tabby's own image is currently broken in CPU-only
containers — see the recipe.)

Default credentials are in the compose file — change them before exposing
anything publicly.

## Why this is different

| Everyone else                                      | Basecamp                                   |
|----------------------------------------------------|--------------------------------------------|
| Manual compose file, hand-wired URLs               | Auto-discovers your stack on first boot    |
| One hardcoded provider                             | Picks the best brain it finds, falls back to its own Ollama |
| Agent config touches your host install             | Container-only, env-scoped, cannot clobber a host Hermes |
| Separate agent + separate model server             | One image, both inside, batteries included |

## Safety model (read this first)

Basecamp is **container-only** and is designed so it can never damage a Hermes
install on the host that runs it:

- **No writes into any Hermes home it doesn't own.** Hermes runtime config
  (provider URL, key, model) is passed as **environment variables**, sourced
  from `basecamp.env` (chmod 600) at `exec` time. Basecamp never overwrites
  `config.yaml` or `.env` files — not in the container, and certainly not on
  the host.
- **State lives in named volumes only.** `basecamp-hermes` → `/root/.hermes`
  and `basecamp-ollama` → `/root/.ollama` inside the container. Nothing on the
  host is modified by running basecamp.
- **No secrets in the image.** API keys are collected at the connect screen,
  saved chmod 600 inside the volume, and injected into the dynamically
  generated `tavern` CLI. The static fallback `tavern.sh` ships with empty key
  placeholders.
- **Hermes is installed with the official installer**, never
  `pip install hermes-cli` (that PyPI package is an unrelated stub, not Hermes
  Agent).

## Quick start

```bash
# Option A: pull the prebuilt image (Docker Hub)
docker pull jpanasuk/basecamp:1.0.6

# Option B: build from source
docker build -t local/basecamp:latest .

# Run against your AI docker network (named volumes keep state across runs)
docker run -it --rm \
  --name basecamp \
  --network your-ai-network \
  --gpus all \
  -p 11436:11434 \
  -v basecamp-ollama:/root/.ollama \
  -v basecamp-hermes:/root/.hermes \
  jpanasuk/basecamp:1.0.6
```

Or use the convenience launcher (auto-detects network + GPU, TTY-safe):
```bash
./basecamp.sh
```

First run shows the connect screen: pick your inference engine, enter API keys
when prompted. Later runs skip it — config is saved in the volume.

## What it discovers

| Service        | What Basecamp does with it                          |
|----------------|-----------------------------------------------------|
| Ollama         | Primary/secondary brain, lists available models     |
| TabbyAPI / vLLM / LiteLLM / LocalAI / llama.cpp | Primary inference engine (OpenAI-compatible) |
| SearXNG        | Wires search into the agent + tavern CLI            |
| MCPO           | Exposes MCP tools to the agent                      |
| Open WebUI / SillyTavern | Detects your chat UIs, reports them         |

## Inside the container

| Command              | What it does                                   |
|----------------------|------------------------------------------------|
| `tavern status`      | Show connected services                        |
| `tavern chat "hi"`   | Chat with your primary inference (streaming)   |
| `tavern models`      | List available models                          |
| `tavern search "q"`  | Search via discovered SearXNG                  |
| `tavern mcp`         | List/call discovered MCP tools                 |
| `tavern rediscover`  | Re-scan for services                           |
| `hermes`             | The Hermes Agent CLI, pointed at your stack    |
| `ollama`             | Manage basecamp's bundled Ollama               |

## Layout

```
basecamp/
├── Dockerfile         # ubuntu:22.04 + Ollama + Hermes (official installer)
├── discover.py        # network scan, connect screen, tavern generator
├── tavern.sh          # static fallback CLI (no secrets)
├── entrypoint.sh      # first-run connect screen, env-scoped hermes config
├── basecamp.sh        # host-side launcher (docker only — never touches host config)
└── supervisord.conf   # Ollama only (hermes is exec'd, not supervised)
```

## Credits

Basecamp is a **packaging of [Hermes Agent](https://hermes-agent.nousresearch.com)** by
[Nous Research](https://nousresearch.com) — all agent intelligence, tools,
skills, and the gateway are theirs. Basecamp's only contribution is the box:
the Docker packaging, the network auto-discovery, the safe env-scoped
wiring, and the `tavern` toolkit. Full credit and gratitude to the Hermes
team for building the agent that makes this project worth shipping.

## Development notes

- Test discovery locally without touching anything:
  `BASECAMP_CONFIG=/tmp/bc.json BASECAMP_DISCOVERY=/tmp/bc-disc.json BASECAMP_ENV_FILE=/tmp/bc.env python3 discover.py serve`
- `discover.py` is container-only by design. It writes only to paths given by
  `BASECAMP_CONFIG` / `BASECAMP_DISCOVERY` / `BASECAMP_ENV_FILE` (defaults are
  under `/root/.hermes` / `/opt/basecamp` inside the container).
- If a secret ever leaks into this repo: rotate it, then scrub git history
  before publishing.