{"id":50495348,"url":"https://github.com/johnforfar/openmesh-support-agent","last_synced_at":"2026-06-02T06:30:30.659Z","repository":{"id":350412163,"uuid":"1206655184","full_name":"johnforfar/openmesh-support-agent","owner":"johnforfar","description":null,"archived":false,"fork":false,"pushed_at":"2026-04-10T08:59:14.000Z","size":69,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-10T09:29:15.627Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/johnforfar.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-10T06:00:04.000Z","updated_at":"2026-04-10T08:59:22.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/johnforfar/openmesh-support-agent","commit_stats":null,"previous_names":["johnforfar/openmesh-support-agent"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/johnforfar/openmesh-support-agent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnforfar%2Fopenmesh-support-agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnforfar%2Fopenmesh-support-agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnforfar%2Fopenmesh-support-agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnforfar%2Fopenmesh-support-agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/johnforfar","download_url":"https://codeload.github.com/johnforfar/openmesh-support-agent/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnforfar%2Fopenmesh-support-agent/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33810341,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-02T02:00:07.132Z","response_time":109,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-02T06:30:29.589Z","updated_at":"2026-06-02T06:30:30.650Z","avatar_url":"https://github.com/johnforfar.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Openmesh Support Agent\n\nA RAG-powered docs assistant that helps developers and AI agents deploy\napps to sovereign Openmesh Xnodes via the [`om` CLI](https://github.com/johnforfar/openmesh-cli).\n\nLive at: **https://chat.build.openmesh.cloud**\n\nRuns entirely on a sovereign decentralized Xnode. No SaaS, no telemetry,\nno OpenAI key. Local LLM, local vector database, local web server.\n\n---\n\n## What it does\n\nYou ask a question about the `om` CLI, deployment patterns, error codes,\nNixOS containers, or Claude Code integration. The agent retrieves the most\nrelevant chunks from its document corpus, feeds them to a local\n`llama3.2:1b` running on the same xnode, and returns an answer with source\ncitations.\n\nThe corpus is multi-source:\n\n1. The **canonical CLI docs** from `johnforfar/openmesh-cli`\n2. The **OpenxAI documentation** from `OpenxAI-Network/openxai-docs`\n3. This repo's own `docs/` folder (instance-specific notes)\n\nAll three are pulled in as flake inputs at build time, so the corpus is\nversioned with the deployment.\n\n---\n\n## How it was deployed\n\nTwo `om` commands. That's the whole story:\n\n```bash\nom app deploy support-agent \\\n  --flake github:johnforfar/openmesh-support-agent\n\nom app expose support-agent \\\n  --domain chat.build.openmesh.cloud \\\n  --port 80\n```\n\nIf you want to do the same thing for your own project, read\n[OPENMESH-SKILLS.md](https://github.com/johnforfar/openmesh-cli/blob/main/OPENMESH-SKILLS.md)\nin the openmesh-cli repo. It's the canonical guide to deploying anything\non a sovereign Xnode via Claude Code or any AI agent.\n\n---\n\n## Architecture\n\nOne nixos-container with four services:\n\n```\n┌─────────────────── nixos-container ────────────────────┐\n│                                                        │\n│   nginx :80                                            │\n│   ├── /              → static frontend (one HTML file) │\n│   └── /api/*         → 127.0.0.1:5000 (python backend) │\n│                                                        │\n│   python backend :5000 (Flask)                         │\n│   ├── /api/health    → status + chunk count           │\n│   └── /api/chat      → embed → retrieve → LLM         │\n│           │                                            │\n│           ├──→ postgres :5432 (pgvector)               │\n│           │       table: chunks(source, content,       │\n│           │                     embedding vector(768)) │\n│           │                                            │\n│           └──→ ollama  :11434                          │\n│                  ├── llama3.2:1b      (chat, ~1.3GB)   │\n│                  └── nomic-embed-text (embed, ~270MB)  │\n│                                                        │\n└────────────────────────────────────────────────────────┘\n                          │\n                          ▼\n            xnode-manager reverse proxy\n                  (TLS via ACME)\n                          │\n                          ▼\n                chat.build.openmesh.cloud\n```\n\n**Memory budget:** ~5 GB total at runtime. Fits comfortably on the\n8 vCPU / 16 GB Xnode.\n\n**On startup the backend:**\n1. Waits for postgres + ollama to come up\n2. Creates schema if missing (`CREATE EXTENSION vector`,\n   `CREATE TABLE chunks`)\n3. Truncates `chunks` and re-ingests every `.md`/`.mdx` file under the\n   configured `DOCS_PATHS` directories\n4. Starts serving HTTP requests\n\nRe-deploying the flake (with updated docs) always produces a fresh\ncorpus — no cache invalidation bugs.\n\n---\n\n## Repo layout\n\n```\n.\n├── flake.nix                  # nixos-container module + flake inputs\n├── flake.lock\n├── backend/\n│   └── app.py                 # ~330 lines: ingestion + retrieval + Flask\n├── frontend/\n│   └── index.html             # vanilla HTML+CSS+JS, no build step\n├── docs/                      # this repo's local doc corpus\n│   └── 01-openmesh-cli-quick.md\n├── tests/\n│   └── verify_deployment.py   # 16 end-to-end checks for live deployments\n└── README.md\n```\n\nThe Python backend is intentionally a single file (~330 lines) so anyone\nwho knows basic Python can read the whole RAG implementation in 10\nminutes. No frameworks, no abstraction layers, no magic.\n\n---\n\n## Verifying a deployment\n\nAfter `om app expose ...` succeeds, run the verification suite:\n\n```bash\npython tests/verify_deployment.py https://chat.build.openmesh.cloud\n```\n\nIt checks:\n\n- **Transport:** HTTPS reachable, TLS cert valid\n- **Health:** `/api/health` returns ok with `chunks_loaded \u003e 0`\n- **Latency:** health endpoint \u003c 5s, cold chat \u003c 90s, warm chat \u003c 60s\n- **Input validation:** empty/oversize queries return 4xx\n- **Knowledge:** 5 questions whose answers are in the docs must produce\n  responses with the right keywords AND at least one cited source\n- **Negative tests:** off-topic questions (Bitcoin price, write a poem)\n  must be politely refused, not hallucinated\n\nExit code is 0 on full pass. Use `--json` for CI consumption.\n\n---\n\n## Reusing this for your own docs\n\nThe shortest path is **fork-and-edit**:\n\n1. Fork this repo\n2. Edit `flake.nix`:\n   - Change the `inputs.openxai-docs` and `inputs.openmesh-cli-docs`\n     entries to point at your own docs flakes (or just remove them and\n     add files to `docs/`)\n   - Change `BRAND_NAME` and the system prompt\n3. Commit and push\n4. Deploy:\n   ```bash\n   om app deploy my-docs --flake github:youruser/your-fork\n   om app expose my-docs --domain support.yourproject.com --port 80\n   ```\n\nOr — and this is the actual point of the project — **don't fork at all.**\nUse `om` directly on whatever app you're already building. The support\nagent is one example; your own app is the actual goal.\n\n---\n\n## Why local LLMs over GPT-5 / Claude\n\nThree reasons:\n\n1. **Sovereignty.** Your docs and queries never leave your infrastructure.\n   No vendor account, no API key, no terms of service that change next quarter.\n2. **Cost.** A 1B parameter model on CPU is free at the margin. Hosted\n   APIs are pennies per query but they add up — and stop working when\n   the vendor rate-limits you the day before your hackathon demo.\n3. **It actually works.** RAG with a small grounded model is competitive\n   with much larger ungrounded models on docs Q\u0026A. The model doesn't have\n   to know the answer; it just has to summarise the chunks the retriever\n   handed it.\n\nWhen the corpus grows past what `nomic-embed-text` and `llama3.2:1b` can\nhandle, swap in `nomic-embed-text-v1.5` (still small) and `llama3.2:3b`\nor `qwen2.5:7b`. The architecture doesn't change.\n\n---\n\n## Credits\n\n- **Openmesh** — sovereign Xnode infrastructure\n- **OpenxAI** — open-source AI alignment + the docs corpus that grounds half the agent\n- **`om` CLI** — what makes the whole thing deployable in two commands ([repo](https://github.com/johnforfar/openmesh-cli))\n- **ollama** — making local LLMs effortless\n- **pgvector** — the simplest vector database that works\n- **Claude Code** — the AI pair-programmer that built and deployed all of this\n\n---\n\n*Deployed with Openmesh CLI v2.0 via Claude Code — [John Forfar](https://github.com/johnforfar)*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjohnforfar%2Fopenmesh-support-agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjohnforfar%2Fopenmesh-support-agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjohnforfar%2Fopenmesh-support-agent/lists"}