Early alpha — core gateway, auth, dashboard, and setup wizard work.
Expect rough edges; breaking changes between releases are likely.
Open an issue if you hit a bug.
Release history note: v0.4 shipped 57 tagged patch releases (v0.4.26–v0.4.105) before graduating to v0.5. Pre-v0.5 tags have been removed from GitHub to keep the releases page clean; the commit history is fully intact.
A self-hosted platform for agentic AI.
Logos is a control plane for AI agents — not a single agent, but a platform you run on your own hardware under your own rules. Agent runtimes plug in; you assemble what you need from five dimensions:
Soul · Tools · Agent · Model · Policy
That combination is a STAMP — it defines every run Logos records, making every agent interaction observable, reproducible, and auditable. No black-box behaviour you can't inspect.
Run on a $5 VPS, a homelab Kubernetes cluster, or serverless infrastructure. During onboarding you choose your privacy model: local inference, self-hosted endpoints, or cloud providers (Anthropic, OpenAI, OpenRouter).
┌──────────────────────────────────────────┐
│ Logos Platform │
│ │
Telegram ─────────► │ Gateway / Router │
Web Dashboard ──────► │ ├── MCP Gateway ──► MCP Servers │
ACP (IDE) ──────────► │ │ (runs inside (filesystem, │
│ │ gateway) GitHub, etc.) │
│ ▼ │
│ Auth & Policy Layer │
│ │ │
│ ▼ │
│ Agent Runtime (e.g. Hermes) │
│ │ │ │
│ ▼ ▼ │
│ Tools Sub-agents │
│ │ │ ▲ │
│ └────┬─────┘ │ request_mcp_access │
│ │ │ (HTTP to gateway) │
│ ▼ │ │
│ Model Router │ │
│ │ │ │ │
└────┼─────────┼─────┼────────────────────┘
▼ ▼
Local Anthropic OpenRouter
(Ollama) (Claude) (200+ models)
Request lifecycle:
- A message arrives via Telegram, the web dashboard, or an ACP-connected editor.
- The Gateway authenticates the request and applies the per-user policy snapshot.
- The Agent Runtime (currently Hermes) processes the conversation through its tool loop.
- Tool calls execute inside an isolated workspace — scoped to the policy level you've set.
- The Model Router dispatches inference to whichever backend you've configured (local GPU, cloud, or both).
- The completed run is written to SQLite as a STAMP record — full tool trace, approval events, token counts, and outcome — queryable and replayable at any time.
Key boundaries:
gateway/— the always-on process: HTTP server, Telegram adapter, auth, routing, web dashboardagent/— runtime adapters; Hermes is the first, additional runtimes plug in vialogos/agent/interface.pytools/— capabilities the agent can call; scoped per session and per policy level- The platform layer (gateway, router, auth, dashboard) is runtime-agnostic;
hermes_*modules belong to the Hermes runtime specifically
Run agents-as-a-service across your infrastructure. Once an agent knows your setup it can query Prometheus, read logs, SSH into machines, inspect containers, and automate deployments.
A personal AI dev partner with IDE integration that browses the web, runs code, edits files, searches codebases, and remembers how you work — without sending code to a third party.
Different people, different agents: different personalities, different model capabilities, different permission levels — all from one deployment.
Local-first agentic AI. Your data stays on your hardware.
Test agentic combinations, then modify, extend, and break the platform and its adapters without worrying about SLAs.
Some things you could ask an agent on Logos:
- "Process the newest Prometheus metric labels and build me alerts and a dashboard."
- "Send me a report every day at 9am about X, Y, and Z — and ask me for feedback."
- "Spin up a research task that reads 20 web pages, cross-references them, and writes a summary — locally, privately."
- "The last request failed — investigate your logs and agent code to examine the cause."
- Runs agents — Hermes is the current runtime, with a clean adapter interface for additional runtimes
- Records everything — every run captures its full STAMP: agent, model, soul, tools, policy, tool sequence, approval events, token counts, and outcome
- Enforces policy — workspace isolation, command approval, filesystem scoping, built-in policy evals
- Reaches you anywhere — Telegram and a built-in web dashboard, all from a single gateway process
- Web dashboard — full chat UI at
http://localhost:8080; real-time streaming, per-message stats, voice input, metrics, multiple agent instances, and a live execution panel - Persistent history — searchable conversation history in SQLite with full-text search across all past conversations
- Voice input — speak via Telegram or the dashboard; faster-whisper transcribes locally by default
- Image support — send images directly; the vision pipeline enriches context before passing it to the model
- Live execution view — watch in real time which tools the agent calls, its chain of reasoning, and elapsed time per step
- AI routing layer — routes requests across machines based on model class, availability, and per-user priority profiles
- Parallel sub-agents — spawn sub-agents via delegation or Mixture-of-Agents, each with independent tool policies and model selection
- MCP gateway — centralized Model Context Protocol server management; MCP servers boot once in the gateway, agents request access dynamically with per-category approval tiers
- Memory system — agent-curated persistent memory, FTS5 session search with LLM summarisation, autonomous skill creation
- Scheduling — cron jobs with Telegram delivery
- Workflow engine — JSON-defined task graphs with DAG execution, parallel steps, conditional branching, and human approval gates
- Self-improvement — the Evolution system lets agents propose code improvements on a schedule; you review, question, or accept each proposal
- IDE integration — ACP protocol for VS Code, Zed, and JetBrains
- Model support — Anthropic, OpenAI, OpenRouter (200+ models), Nous Portal, or any OpenAI-compatible endpoint
- Runs anywhere — local, Docker, SSH
- Cancel mid-response — abort any in-flight request without waiting for it to finish
Every run in Logos is defined by five dimensions:
| S — Soul | The persona: how the agent communicates, reasons, and behaves |
| T — Tools | The capabilities available: what the agent can reach and act on |
| A — Agent | The runtime: which adapter processes the conversation |
| M — Model | The brain: which LLMs are called to execute functions |
| P — Policy | The rules: what the agent is allowed to do, approve, or refuse |
Compose these five and you have an AI agent. Change any one dimension and you have a different seeded agent. Every STAMP is recorded in full — compare runs across configurations, replay them exactly, or clone them into new sessions.
The soul lives in SOUL.md, editable without a restart. Tools are scoped per platform and per session. The agent adapter is switchable. The model switches without code changes. Policy is enforced at the workspace and approval layers, not just in the prompt.
Understanding the isolation boundary matters before you choose how to run Logos. Agents can read files, execute code, and make network requests — what they cannot reach depends entirely on your deployment mode.
| Mode | How it's run | Isolation boundary | Network policy | Agents can reach… |
|---|---|---|---|---|
| Local process | pip install logos / Windows .exe |
OS process boundary | None | Your user's home directory and whatever that user can reach on the host |
| Container sandbox | Docker Desktop (Windows/macOS) | Docker container boundary | None (outbound unrestricted) | Files inside the container only; host filesystem not mounted |
| Full sandbox (OpenShell) | Docker + OpenShell CLI (Linux/macOS) | Docker container + egress policy | OpenShell YAML policy enforcement | Container-only filesystem; outbound restricted to policy allowlist |
| Docker Compose | docker-compose.yml |
Container boundary | None | Files/processes inside the container only; the host filesystem is not mounted |
| Docker Compose + k3s | docker-compose.k3s.yml |
Kubernetes pod boundary | K8s NetworkPolicy capable | A fresh pod with its own filesystem and network namespace per agent |
| External Kubernetes | k8s/ manifests |
Kubernetes pod + RBAC boundary | K8s NetworkPolicy capable | Pod resources only; network policies and RBAC apply |
Agents run as child processes of the gateway, inheriting the same user account. There is no additional sandbox beyond normal OS process isolation. An agent that calls the terminal tool can read and write anything your user account can.
This is the last-resort fallback when neither Docker nor Kubernetes is available. The setup wizard clearly labels this mode.
Mitigations:
- Keep policy level at
WORKSPACE_ONLYor lower to restrict filesystem access to the working directory. - Run Logos under a dedicated low-privilege user account, not your daily-driver account.
When Docker Desktop is available but the OpenShell CLI is not (currently the case on Windows, where OpenShell does not ship binaries), Logos can still run agents inside Docker containers. Each agent gets its own isolated container with:
- Separate filesystem (host filesystem not mounted)
--cap-drop=ALL(no Linux capabilities)--security-opt=no-new-privileges- Localhost-only port binding
- Auto-cleanup on exit (
--rm)
What this mode does NOT provide: egress policy enforcement. Agents can make outbound network requests to any destination. If your use case requires network restriction, use Kubernetes with NetworkPolicy or wait for OpenShell Windows support.
The strongest desktop isolation. OpenShell manages Docker containers with a declarative YAML policy layer that controls:
- Which network destinations agents can reach (egress allowlist)
- GPU passthrough for local inference
- Container lifecycle and resource limits
Platform support: Linux and macOS only. OpenShell does not currently ship Windows binaries. The setup wizard detects this automatically and offers Container sandbox mode as the Windows alternative.
Logos and all its agents run inside a single Docker container. The host filesystem is not mounted — agents can only see what's inside the container. They cannot read your .env file, home directory, or other host files.
Host OS
└── Docker container ← isolation boundary
├── Logos gateway
└── Agent processes (child processes inside the same container)
What agents cannot do: escape the container, read host files, reach host network services (unless you expose ports in docker-compose.yml).
What agents can do: read/write files inside the container, make outbound HTTP requests, call the tools you've enabled.
To start:
cp .env.example .env # add your API keys + HERMES_JWT_SECRET
docker compose up -dEach agent session spawns a dedicated Kubernetes pod inside an embedded k3s cluster. Pods have their own filesystem, network namespace, and resource limits — agents are isolated from each other and from the Logos gateway container.
Host OS
└── Docker network
├── k3s container (privileged) ← runs the Kubernetes control plane
└── logos container
└── Agent pods (k8s pods in the hermes namespace) ← per-agent isolation boundary
Requirements: Linux host only. k3s requires a privileged container and Linux namespaces/cgroups — this does not work on Docker Desktop for Mac or Windows without extra configuration.
To start:
cp .env.example .env # add HERMES_JWT_SECRET (required)
docker compose -f docker-compose.k3s.yml up -d
# In setup wizard step 4: choose Kubernetes → "Logos is outside the cluster"
# Leave kubeconfig empty — it is mounted automatically.Deploy Logos to an existing cluster. Agent pods run in the hermes namespace with full Kubernetes isolation. You can layer network policies and RBAC on top for production deployments.
Quick start:
# 1. Create the namespace and apply manifests
kubectl apply -f k8s/
# 2. Set required secrets
kubectl create secret generic logos-secrets -n logos \
--from-literal=HERMES_JWT_SECRET=$(openssl rand -hex 32) \
--from-literal=OPENAI_API_KEY=<your-key> # or whichever provider you use
# 3. Check rollout
kubectl rollout status deployment/logos -n logosIn the setup wizard, step 4: choose Kubernetes → "Logos is inside the cluster" and leave kubeconfig empty — the in-cluster service account is used automatically.
See k8s/README.md for full manifest reference, ingress setup, and persistent volume configuration.
Agent security is defense-in-depth — multiple independent layers, not a single boundary:
| Layer | What it does | Where it runs |
|---|---|---|
| Workspace scoping | Restricts file read/write to the agent's workspace directory. Symlink-safe (realpath before access check). |
All modes |
| Toolset enforcement | Agents can only call tools in their enabled toolset. Validated at agent init and registry dispatch. | All modes |
| API key filtering | Terminal subprocesses don't receive provider API keys (OPENAI_API_KEY, etc.). Built from provider registry. |
All modes |
| Command review | Regex patterns catch common destructive shell commands (rm -rf /, DROP TABLE, chmod 777, etc.). Prompts for approval before execution. |
All modes |
| Tirith scanning | Pre-execution semantic analysis of shell commands for content-level threats (homograph URLs, pipe-to-interpreter, terminal injection). Auto-installed from GitHub releases. | Linux, macOS |
| Container isolation | Agent runs in a Docker container with --cap-drop=ALL, --security-opt=no-new-privileges, no host filesystem mounts. |
Container sandbox, OpenShell, k8s |
| Egress policy | Declarative YAML policy controls which network destinations the agent can reach. | OpenShell only |
| NetworkPolicy | Kubernetes-native network restriction. Agent pods can only reach DNS, HTTPS, the gateway, and inference server ports. | k8s only |
Command review catches obvious destructive patterns but is bypassable with interpreter one-liners (e.g. python -c "import shutil; ..."). It is a convenience layer, not a security boundary. The real protection comes from workspace scoping (all modes), container isolation (Docker/k8s modes), and egress policies (OpenShell/k8s).
Tirith is not available on Windows. When absent, the command review regex patterns are the only pre-execution check. On Linux/macOS, Tirith is auto-downloaded at startup and provides deeper analysis.
HERMES_JWT_SECRET
All session tokens are signed with this secret. Generate it once with openssl rand -hex 32 and store it somewhere safe.
- If you lose it, all active sessions are invalidated on next restart (users will need to log in again — no data is lost).
- Rotating it intentionally: change the value, restart Logos.
- Never commit it to version control.
HERMES_COOKIE_SECURE
Set to true if Logos is behind an HTTPS reverse proxy (nginx, Caddy, Traefik). This adds the Secure flag to auth cookies so they are only sent over HTTPS.
- Leave empty for plain HTTP (local or docker-compose without TLS termination).
- Do not expose Logos directly on the internet without TLS.
API keys in .env
In Docker deployments, API keys live in the .env file on the host — they are passed as environment variables to the container and are not visible to agents (agents cannot read the host .env file or process environment of the gateway). On bare metal, agents run in the same process environment, so a sufficiently capable agent could read them via os.environ.
By default Logos binds to 0.0.0.0:8080, making the dashboard reachable from any interface. In a homelab or VPS deployment:
- Put it behind a reverse proxy (nginx, Caddy) with TLS.
- Use firewall rules to restrict access to trusted IPs if you don't have a proxy.
- The Telegram integration lets you reach your agent without exposing the web UI at all.
Which path is for me?
| I want to… | Use |
|---|---|
| Try Logos on Linux / macOS / WSL2 | Bash installer |
| Run on Windows without WSL2 | Windows installer |
| Strongest self-hosted isolation (Linux host) | Docker Compose + k3s |
| Standard Docker deployment | Docker Compose |
| Deploy to an existing Kubernetes cluster | External Kubernetes |
Before running: you can inspect the installer first:
curl -fsSL https://raw.githubusercontent.com/GregsGreyCode/logos/main/scripts/install.sh | less
curl -fsSL https://raw.githubusercontent.com/GregsGreyCode/logos/main/scripts/install.sh | bashWorks on Linux, macOS, and WSL2. Handles Python, Node.js, and dependencies automatically. No prerequisites except git.
After the installer finishes:
# Add your API keys / JWT secret (open in any editor)
nano ~/.logos/config.yaml # or edit via the setup wizard at http://localhost:8080
# Start Logos
logos # or: python -m gateway.http_apiOpen http://localhost:8080 — the setup wizard launches automatically on first run.
A native Windows installer (.exe) is available on the GitHub Releases page. No WSL2 required.
What the installer does:
- Installs a self-contained Python + Node.js environment under
%LOCALAPPDATA%\Logos - Creates a start menu entry and system tray icon
- Starts the Logos gateway automatically
After installation:
- Logos opens in the system tray — right-click the icon to open the dashboard
- Navigate to
http://localhost:8080in your browser - The setup wizard launches automatically — it will prompt you for any API keys it needs
- Your configuration is saved to
%USERPROFILE%\.logos\config.yaml
Sandbox on Windows: If Docker Desktop is installed, the setup wizard offers Container sandbox mode — each agent runs in its own isolated Docker container. Without Docker, agents run in-process (local process mode). OpenShell is not yet available on Windows.
Logos is currently unsigned. Windows SmartScreen may show "Windows protected your PC" on first run. Click "More info" → "Run anyway" to proceed.
You can verify that what you downloaded is exactly what was built using the methods below.
Logos binaries are built exclusively via GitHub Actions — no local machines, no manual steps, no hidden stages.
- Source → build → artifact pipeline is fully public
- Every release links to the exact CI run that produced it
- View all builds
Every release publishes SHA256 hashes for both the installer and the inner Logos.exe. These appear in the GitHub Release notes, in SHA256SUMS.txt, and in a .sha256 sidecar file — all produced by the same CI run.
# Windows — replace X.Y.Z with the version you downloaded
certutil -hashfile LogosSetup-X.Y.Z.exe SHA256
# Compare the output to the hash in the GitHub Release notes# macOS / Linux
sha256sum LogosSetup-X.Y.Z.exeEach release is scanned on VirusTotal — the scan link is included in the GitHub Release notes. You can also drag-and-drop your downloaded file at virustotal.com to run your own scan.
On first run, the setup wizard walks you through:
- Choosing your LLM provider and model (local, Anthropic, OpenAI, or OpenRouter)
- Connecting inference servers — Logos scans your local network automatically
- Benchmarking candidates to find the best model for your hardware
- Choosing your agent runtime and soul
- Setting your policy level and workspace isolation mode
- Optionally connecting Telegram
Platform-specific choices in the wizard:
| Platform | Step 4 — Execution backend |
|---|---|
| Bare metal (Linux / macOS / Windows) | Local (default) |
| Docker Compose | Local (agents run inside the container) |
| Docker Compose + k3s | Kubernetes → "Logos is outside the cluster" |
| External Kubernetes | Kubernetes → "Logos is inside the cluster" |
Your configuration lives in ~/.logos/config.yaml (Linux/macOS/WSL2) or %USERPROFILE%\.logos\config.yaml (Windows).
📹 [Video walkthrough coming soon]
0:00 — Install and start
Run the installer and open http://localhost:8080. You should see the Logos dashboard.
2:00 — Complete the setup wizard
The wizard launches automatically on first run. Choose a model (cloud API key or local Ollama endpoint), run the benchmark, and leave policy at WORKSPACE_ONLY for now. You can change everything later.
4:00 — Send your first message
Ask the agent something simple. Watch the live execution panel — you'll see exactly which tools it calls, in order, and how long each step takes. This is the STAMP model in action.
Try: "What can you see about the machine you're running on?"
6:00 — Edit your soul
Open ~/.logos/SOUL.md in any editor. Change the agent's name, tone, or give it a specific focus. Save — no restart needed. Send another message and notice the difference.
Try adding: "Always respond concisely. You are a homelab assistant named Atlas."
8:00 — Inspect a run
From the dashboard, open Runs. Click the run you just created. You'll see the full tool trace, token counts, and outcome. Hit Clone to open a new session seeded from that exact configuration.
10:00 — Where to go next
- Connect Telegram so you can reach your agent from anywhere
- Swap the model to something local if you haven't already
- Try a more complex prompt — ask it to read a log file, query a URL, or write and run a script
- Explore
workflows/examples/for pre-built task graphs
When you connect a local inference server (Ollama or LM Studio), the setup wizard automatically benchmarks your available models to find the best fit for driving the agent.
Up to 4 candidates are selected by sampling across size buckets: small (<5B), mid (5–13B), large (>13B), and unknown. One representative per bucket, then remaining slots filled from the best of the rest.
Within each bucket, models are ranked by quality heuristics:
- Mid: closest to the 9B sweet spot (large enough to reason, fast enough to use)
- Small: largest available (4–5B beats 1–3B)
- Large: smallest available (14B beats 70B on throughput)
- Unknown: names containing
instruct,chat,tool,assistantare preferred
Two passes per model on different prompt types:
| Pass | Prompt type | Purpose |
|---|---|---|
| 1 | Natural language prose | Baseline throughput |
| 2 | Structured JSON output | Throughput under formatting constraints |
The two results are averaged. Time-to-first-token (TTFT) is measured on pass 1. Throughput is measured from first token to last, so cold-start latency doesn't inflate the tok/s figure.
| Label | Tokens/sec | Notes |
|---|---|---|
| Fast | ≥ 30 | Comfortable for interactive use |
| Good | ≥ 15 | Responsive for most tasks |
| Usable | ≥ 6 | Acceptable; notable latency on long outputs |
| Slow | < 6 | Likely too large for real-time agent use on this hardware |
| # | Test | Pass condition |
|---|---|---|
| 1 | Instruction following | 4-step ordered task: all four outputs present |
| 2 | Arithmetic reasoning | Two-part maths problem: both answers correct |
| 3 | Strict JSON format | Output parses cleanly as JSON with exact field values; extra prose fails |
| 4 | Tool selection | Routes two scenarios to the right tool; both must be correct |
A model passes the capability bar at ≥ 3/4 tests.
score = 0.45 × (eval_tests_passed / 4)
+ 0.30 × min(tok_s, 40) / 40
+ 0.15 × ttft_score (1.0 at ≤500ms, 0.0 at ≥4s)
+ 0.10 × min(param_count_B, 13) / 13
- Eval quality (45%) — weighted most heavily; a fast but unreliable model produces poor agent outcomes
- Speed (30%) — capped at 40 tok/s; returns above that have diminishing value for interactive use
- TTFT (15%) — time-to-first-token affects perceived responsiveness
- Model size (10%) — all else equal, a larger model is preferred; capped at 13B
Between tests, each model is explicitly unloaded from GPU memory to prevent contention. If you connect more than one inference server, each server's models are tested in parallel with other servers — but models on the same server run sequentially to prevent VRAM contention.
Soul — edit ~/.logos/SOUL.md at any time. Changes take effect on the next message; no restart needed.
Tools — enable or disable per platform via the web dashboard or by editing the toolsets key in ~/.logos/config.yaml.
Agent — choose which runtime processes your conversation. Currently available: Hermes (general-purpose, full tool loop). Additional agents register via logos/agent/interface.py. ACP clients (VS Code, Zed, JetBrains) connect through the ACP adapter.
Model — switch via the web dashboard or by setting openai.base_url in config for any OpenAI-compatible endpoint.
Policy — set workspace isolation mode (FULL_ACCESS, WORKSPACE_ONLY, REPO_SCOPED, READ_ONLY), configure command approval callbacks, and run policy enforcement evals from the dashboard.
/runs list # recent runs with status and token counts
/runs detail <id> # full tool trace, approval events, outcome
/runs replay <id> # re-run a message in the same session
/runs clone <id> # seed a new session from a prior run
/evals run <suite> # execute an eval suite
/evals results # view past eval results
/metrics # usage dashboard
/metrics prometheus # Prometheus export for scraping
Every log line includes a [session_id] field set via a contextvars.ContextVar at the start of each request — grep a single session ID across gateway, agent, and tool logs without any thread-local state.
GET /healthz returns per-platform success and error counters (platform_stats), useful for spotting silent adapter failures across Telegram, Discord, Slack, and other connected platforms.
The Evolution tab gives agents a structured channel to propose improvements to the platform itself, on a schedule you control.
- Agents analyse your codebase on the configured interval. Each agent reads the repository, looks for bugs and complexity hotspots, and drafts a concrete improvement.
- A proposal is submitted — title, summary, a unified diff, and the list of affected files — and appears in the Evolution tab for your review.
- You decide: Accept, Decline, or Ask a question back to the agent.
- Optionally consult a frontier model — ask Claude or GPT-4o to review the proposal before you decide.
Each Logos deployment works against your own fork of the repository. Fork the canonical repo, configure the fork URL in Evolution Settings, and the agent reads from it and opens PRs against it.
Setup: Fork → Evolution Settings → configure fork URL, PAT, base branch, schedule, frontier model → Enable.
API:
GET /evolution/proposals # list (filterable by status)
POST /evolution/proposals # create (agents use this)
POST /evolution/proposals/{id}/decide # accept / decline / question
POST /evolution/proposals/{id}/consult # consult a frontier model
PATCH /evolution/settings # update settings
Logos runs a centralized MCP (Model Context Protocol) gateway inside the gateway process. MCP servers boot once at startup and are shared across all agent sessions — no per-agent subprocess spawning, no config duplication into sandboxes.
The per-agent subprocess model breaks in two critical scenarios:
- OpenShell sandbox: the sandbox container has no access to
~/.logos/config.yaml, so MCP servers can never start inside it. - k8s pods: each pod would need its own MCP server subprocesses, multiplying resource use by session count.
The centralized gateway solves both: agents connect over HTTP regardless of where they're running.
Agent (any executor)
│
│ tools: request_mcp_access("filesystem")
│
▼
Gateway policy check
│
├─ auto_approve category → granted immediately
├─ user_approve category → approval prompt sent to user
└─ admin_approve category → requires admin to approve
│
▼
Grant issued → agent receives MCP tools for that server
│
│ tool calls routed via HTTP
▼
/mcp/{server-name} (JSON-RPC proxy in gateway)
│
▼
MCP server subprocess (boots once at gateway start)
mcp_servers:
filesystem:
command: npx
args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"]
category: local # controls approval tier
description: "Read and write files in ~/projects"
github:
command: npx
args: ["-y", "@modelcontextprotocol/server-github"]
env:
GITHUB_PERSONAL_ACCESS_TOKEN: "${GITHUB_TOKEN}"
category: external
description: "GitHub issue and PR management"
mcp_policy:
auto_approve: [local] # granted without prompting the user
user_approve: [external] # user sees an approval request
admin_approve: [privileged] # only an admin account can approve
# deny: [dangerous] # always blockedcategory is a free-form label you assign to each server — the mcp_policy block maps categories to approval tiers. Any server whose category isn't listed defaults to user_approve.
Agents have two MCP tools always available (in the mcp-gateway toolset):
| Tool | What it does |
|---|---|
get_mcp_catalogue |
Lists all configured MCP servers, their descriptions, and the approval tier |
request_mcp_access |
Requests access to a specific server by name |
When request_mcp_access("filesystem") is called:
- The gateway checks the server's category against
mcp_policy. auto_approve: access granted immediately; MCP tools injected into the session.user_approve: an approval card appears in the web dashboard or Telegram; the agent pauses and resumes when you respond.admin_approve: same flow, but only an admin-role account can approve.
The gateway automatically resolves the right endpoint URL based on where the agent is running:
| Execution mode | Agent connects to |
|---|---|
| Local process (bare metal / Docker) | http://127.0.0.1:{mcp_port}/mcp/{name} |
| OpenShell sandbox | http://host.docker.internal:{mcp_port}/mcp/{name} |
| Kubernetes pod | http://logos-gateway.{ns}.svc.cluster.local:{mcp_port}/mcp/{name} |
The port defaults to 8081 and can be overridden with HERMES_MCP_PORT.
GET /api/mcp/catalogue # list configured servers + policy tiers
GET /api/mcp/status # which servers are running, which failed
POST /api/mcp/grants/{session_id}/{srv} # admin: manually grant access
DELETE /api/mcp/grants/{session_id}/{srv} # admin: revoke access
Grants are in-memory and reset on gateway restart.
hermes claw migrate # interactive migration (full preset)
hermes claw migrate --dry-run # preview what would be migrated
hermes claw migrate --preset user-data # migrate without secretsWhat gets imported: SOUL.md, memories, skills, command allowlist, messaging settings, API keys, TTS assets, workspace instructions.
These are disabled by default and require explicit configuration. Enabling them sends data to third-party providers.
Honcho builds a persistent model of each user across conversations and feeds it back into the agent context on future sessions.
What it does when enabled: syncs conversation messages to Honcho's cloud API, uploads MEMORY.md/USER.md/SOUL.md, runs inference on Honcho's backend to inject user insights into context.
Privacy: your conversations leave your network and are processed by a third party. Do not enable this if data privacy is a requirement.
To enable: set HONCHO_API_KEY in your environment or ~/.honcho/config.json.
Source in gateway/, tools/, and agent/. See AGENTS.md for internals, local dev setup, gateway architecture, and how to add tools.
Runtime support:
| Backend | Status |
|---|---|
| Local (Ollama / LM Studio) | ✅ Tested |
| Docker | ✅ Tested |
| Kubernetes (k3s / external) | ✅ Tested |
| SSH | ✅ Tested |
| Modal | |
| Daytona | |
| Singularity |
docker buildx build \
--platform linux/amd64 \
--build-arg BUILD_SHA=$(git rev-parse --short HEAD) \
-t ghcr.io/gregsgreycode/logos:canary \
--push .
--build-arg BUILD_SHA=...is required — omit it and the version footer displaysunknowninstead of the actual commit SHA.
After pushing, roll out:
kubectl rollout restart deployment/logos -n logos
kubectl rollout status deployment/logos -n logosgit clone https://github.com/GregsGreyCode/logos.git
cd logos
curl -LsSf https://astral.sh/uv/install.sh | sh
uv venv .venv --python 3.11
source .venv/bin/activate
uv pip install -e ".[all,dev]"
uv pip install -e "./mini-swe-agent"
./scripts/test.shWhy these choices:
uv— significantly faster than pip for dependency resolution; the project uses it throughout- Python 3.11 — minimum supported version; 3.12+ untested
mini-swe-agent— vendored directly into the repo; powers the agent's code-editing toolset
Test script options:
./scripts/test.sh # unit tests only — mirrors CI (default)
./scripts/test.sh --integration # unit + integration tests (requires API keys)
./scripts/test.sh --mini # mini-swe-agent tests only
./scripts/test.sh --everything # all suites
./scripts/test.sh --coverage # generate HTML coverage report in htmlcov/
./scripts/test.sh --no-parallel # serial output — easier to read tracebacks
./scripts/test.sh -k "test_foo" # pass extra args through to pytestIntegration tests require live API keys (OPENROUTER_API_KEY, OPENAI_API_KEY, etc.) and hit real external services. Unit tests blank all keys automatically and never make network calls.
RL Training (optional): To work on the RL/Tinker-Atropos integration:
git submodule update --init tinker-atropos uv pip install -e "./tinker-atropos"
MIT — see LICENSE.
This project would not exist without the open-source work it stands on:
- Anthropic / Claude — Claude wrote a significant portion of the gateway, UI, tooling, and this documentation.
- Nous Research / hermes-agent — the Hermes agent runtime (
agents/hermes/) is a heavily extended fork of their open-source hermes-agent. The platform layer (gateway, auth, dashboard, STAMP system, policy enforcement) is original work built on top of it. Thetinker-atroposRL submodule combines Atropos (Nous Research) and Tinker (Thinking Machines Lab). - SWE-agent / mini-swe-agent — vendored directly into the repo (MIT licence), powers the terminal tool's PTY-based shell execution.
- Ollama — makes running local LLMs approachable. Powers the homelab GPU machines that handle inference.
- LM Studio — excellent local model serving, especially for experimentation and first-time model setup.
- faster-whisper — powers in-pod voice transcription without any cloud dependency.
- aiohttp — the async web framework underpinning the entire gateway and HTTP API.
- Alpine.js — the reactive UI layer for the dashboard. Lightweight and pleasant to work with for a single-file SPA.
- Tailwind CSS — makes the dashboard look polished without writing custom CSS.
- marked.js — client-side Markdown rendering for chat messages.
- Talos Linux — the immutable, secure Kubernetes OS running the homelab cluster.
- python-telegram-bot — the Telegram adapter that makes Hermes available anywhere.
- SQLite — server-side chat persistence and full-text search. Quietly does everything.