Local Agent Stack

A Docker Compose stack that runs a capable AI agent on your own machine, private by default, with no cloud service needed for inference. It wires together chat, web search, knowledge graphs, workflow automation, and coding agents. A desktop launcher for non-technical users is on the roadmap.

Quick start

./scripts/setup.sh          # secrets, data/, COMPOSE_PROFILES=core
make doctor                 # Docker, ports, model server from inside a container
# Start a host model server (OpenAI-compatible or Ollama) — or use --ollama
make up
# First Hermes boot only:
docker compose run --rm hermes setup && make up

Open http://localhost:8787 (Hermes WebUI). Dashboard: http://localhost:9119.

Zero-config demo (CPU Ollama in Docker):

./scripts/setup.sh --ollama
make up
docker compose run --rm ollama-pull

On Apple Silicon, Docker cannot reach the GPU. Prefer a host model server (LM Studio, host Ollama, llama.cpp, …) if you care about speed; the ollama profile exists as a self-contained demo path.

Architecture

flowchart TB
  subgraph host [Host]
    LLM["Model server (OpenAI-compatible or Ollama)"]
    Desktop["Desktop launcher roadmap"]
  end
  subgraph core [core profile]
    Hermes[hermes]
    WebUI[hermes-webui]
    Searx[searxng]
    McpSearx[mcp-searxng]
  end
  subgraph rag [rag profile]
    LightRAG[lightrag]
    Neo4j[neo4j]
    LragMcp[lightrag-mcp]
  end
  subgraph calendar [calendar profile]
    CaldavMcp[caldav-mcp]
  end
  subgraph tools [automation / coding]
    N8n[n8n]
    OpenCode[opencode]
    Gptr[gpt-researcher]
  end
  Desktop -.-> core
  LLM --> Hermes
  LLM --> LightRAG
  Hermes --> McpSearx
  Hermes --> LragMcp
  Hermes --> CaldavMcp
  WebUI --> Hermes

Profiles

Examples:

./scripts/setup.sh --rag --calendar --automation --coding
# or edit .env:
# COMPOSE_PROFILES=core,rag,calendar,automation,coding

Security model (what the extra wiring buys you)

• Localhost binds for SearXNG, GPT Researcher, and the Hermes dashboard/API/WebUI. Nothing is LAN-exposed by default.
• Hermes LightRAG MCP allowlist: unattended API sessions get five read-oriented tools out of seventeen, and the bootstrap drops unfiltered clone duplicates so a --cloned profile cannot route around the allowlist.
• Hermes CalDAV MCP allowlist: unattended API sessions get read-only calendar tools; create/update/delete stay on dashboard and WebUI. Account credentials live in gitignored compose/caldav-mcp/accounts/*.env and are copied into Hermes MCP headers under data/hermes/.
• Per-profile API keys for the Hermes api-server and browser gateways. Sharing one key fails closed.
• OpenCode secret shadowing: mount compose/opencode/blank over project .env files via gitignored docker-compose.override.yml.
• Setup writes secrets into gitignored overlays (searxng/settings.local.yml, Hermes *.env) and leaves tracked templates alone.

See SECURITY.md.

Prerequisites

• Docker Compose v2 (Linux, macOS, Windows/WSL2)
• A model server: any OpenAI-compatible API on the host (LM Studio, llama.cpp, vLLM, …), host Ollama, or the ollama profile

#1 gotcha: inside a container, localhost is the container. Reach the host as host.docker.internal. The host server must listen beyond localhost (LM Studio: Serve on Local Network; Ollama: OLLAMA_HOST=0.0.0.0).

Recommended: 16 GB RAM when running a local 7–35B model beside the stack.

Docs

Commands

make setup / ./scripts/setup.sh
make doctor
make model-use MODEL=…          # or FROM_LMSTUDIO=1 (interactive menu), YES=1, PRESET=…
make up / make down / make ps
make logs
make data-dir-show / data-dir-set DIR=… / data-dir-migrate DIR=…
make hermes-upgrade AGENT=v… WEBUI=…
make clean   # destroys volumes + repo ./data/ (not an external ASSISTANT_DATA_ROOT)

Roadmap

• Desktop app that launches and manages this Docker setup for non-technical users
• Harden first-run UX (make doctor coverage, guided model install)

License

MIT — see LICENSE.