This is the maintained map for ODS, the Osmantic Deployment System. It is for
operators, contributors, and reviewers. Links from this directory use ../ for
the ods/ product root and bare filenames
for other docs in this directory. The GitHub landing README lives two levels up
at ../../README.md.
FAQ: ../FAQ.md is the installation and usage FAQ at the product root;
FAQ.md in this directory is the hardware and requirements FAQ.
Use this table as the "you are here" map. ODS has many deep-dive docs because the project covers install, compose, model routing, agents, security, and release validation. Most contributors only need the row that matches the work in front of them.
- September maintenance audit: changes, validation and remaining work outside the testing freeze.
- Third-party licensing review: component restrictions and open work.
- Recipe source register: sources and terms for the 34 recipes missing structured provenance.
- Model terms inventory: 58 catalog entries and source evidence.
- Artwork provenance: file hashes, sources and rights status.
- Contributor ledger: promoted-range attribution without inferred identities.
- Documentation hygiene: link gate and pinned vendor exceptions.
The shortest useful rule is: docs-only changes get docs checks; operational changes get the validation surface they can affect.
| Change type | Start with | Escalate when |
|---|---|---|
| Docs, comments, examples | git diff --check, markdown/link sanity |
The docs change makes or changes a support claim |
| UI-only dashboard work | Dashboard tests, lint, and build | It changes setup, auth, service control, or model workflows |
| Service manifest or extension metadata | Extension audit and catalog validation | It changes compose, ports, health, dependencies, or defaults |
| Installer, compose, CLI, auth, proxy, model routing | Focused tests plus release-grade validation | Always consider this operational code |
| Dependency/runtime wiring | Package tests and service smoke | The package affects installer, dashboard-api, services, or container startup |
Use HIGH_RISK_CHANGE_MAP.md for the full policy and RELEASE_VALIDATION.md for the User Green release gate.
Some docs are canonical contracts; others are operator guides, implementation deep dives, or historical/planned notes. When docs overlap, prefer the canonical source and treat older recipes as context.
| Status | Meaning | Examples |
|---|---|---|
| Canonical contract | Defines behavior reviewers should enforce | HIGH_RISK_CHANGE_MAP.md, INSTALLER_PHASE_CONTRACTS.md, COMPOSE_RESOLVER_CONTRACTS.md, ENGINE-PROVIDER-MODES.md, RELEASE_VALIDATION.md |
| Operator guide | Helps users install, operate, or troubleshoot | ../QUICKSTART.md, ODS-DOCTOR.md, TROUBLESHOOTING.md, POST-INSTALL-CHECKLIST.md |
| Maintainer runbook | Explains how to preserve or release the project | MAINTAINER_RUNBOOK.md, FORKABILITY.md, OFFLINE_AND_MIRRORING.md, VALIDATION_REPRODUCIBILITY.md |
| Deep dive | Explains a subsystem or design area | INSTALLER-ARCHITECTURE.md, BACKEND-CONTRACT.md, ODS_CLI_DECOMPOSITION.md |
| Historical or planned | Records a past migration, launch checklist, or future direction | PROFILES.md, OSS-LAUNCH-CHECKLIST.md, SERVICE_MANIFEST_V2_PLAN.md |
- The golden paths are Linux NVIDIA, Windows with Docker Desktop + WSL2 for NVIDIA/AMD, and Apple Silicon. Linux AMD Strix Halo is actively supported; Intel Arc is present but still experimental.
- Pixel is the preferred agent on qualified Ubuntu 24.04/26.04 or Debian 12
PID1-systemd hosts without a separate acceptance step. Hermes plus
hermes-proxyremains the portable default and rollback path everywhere else. The legacy OpenClaw extension was removed; see MIGRATION-OPENCLAW-TO-HERMES.md. - AMD GPUs run llama.cpp's
llama-serverlike every other backend; ODS no longer uses Lemonade Server. See MIGRATION-LEMONADE-TO-LLAMACPP.md. - Linux Docker installs expose llama-server on host
OLLAMA_PORT=11434by default while containers usellama-server:8080. macOS native Metal and the Windows AMDllama-server.exeuse host port8080unless overridden. - Windows installs should run from a normal user PowerShell, not Administrator.
The default install directory is
$env:USERPROFILE\odsunlessODS_HOMEis set. - Bundled service truth lives in
extensions/services/*/manifest.yaml. Core host-facing port defaults are tracked inconfig/ports.json; per-service manifest defaults live with each service. The dashboard extension library catalog is generated intoconfig/extensions-catalog.json. - Generated runtime config has several writers. If you change
.env, OpenCode, Perplexica, Hermes, LiteLLM or model-router behavior, update the Linux, macOS, Windows, bootstrap-upgrade, and host-agent paths together.
| Doc | Audience | Description |
|---|---|---|
| HOW-ODS-SERVER-WORKS.md | Everyone | The friendly guide — what ODS is, why it exists, how every piece fits together, and how to make it your own. No technical background required. |
| ../../README.md | Everyone | GitHub landing page and public project overview |
| ../README.md | Everyone | Product README, quickstart, architecture, and operator overview |
| ../QUICKSTART.md | Operators | Step-by-step first install |
| INSTALLER_TRUST.md | Operators / reviewers | Inspect-first install paths, release ref pinning, and current provenance limits |
| HEADLESS-SETUP.md | Operators / hardware builders | Hardware-neutral QR onboarding, first-boot setup, AP mode, mDNS, and local-agent access map |
| ../EDGE-QUICKSTART.md | Operators | Edge devices (planned — do not follow yet; use cloud mode for CPU-only today) |
| ../.env.example | Operators | All environment variables with defaults |
| Doc | Audience | Description |
|---|---|---|
| BUILD-ON-ODS-SERVER.md | Downstream builders | Forking, custom editions, source-of-truth map, extension compatibility, and validation checklist |
| FORKABILITY.md | Downstream builders / fork operators | Fork posture, independent operation, safe extension points, and upstream relationship |
| RELEASE_CHANNELS.md | Downstream builders / operators | When to track main, pin a tag, pin a commit, or operate a downstream fork |
| OFFLINE_AND_MIRRORING.md | Fork operators / appliance builders | Pinning, mirroring, and preserving release artifacts for offline or independent operation |
| VALIDATION_REPRODUCIBILITY.md | Fork operators / release reviewers | How to reproduce upstream validation layers on local hardware and record receipts |
| EXTENSIONS.md | Builders | Add Docker services, manifests, dashboard plugins |
| SWAP-SAFE-EXTENSIONS.md | Builders / reviewers | Make LLM-consuming extensions model-swap-safe with the gateway alias and service.llm contract |
| ../extensions/templates/README.md | Builders | Starter manifest, compose, GPU overlay, and dashboard plugin templates |
| ../extensions/CATALOG.md | Builders / reviewers | Current bundled service manifest catalog |
| SERVICE_MANIFEST_V2_PLAN.md | Maintainers / extension reviewers | Non-breaking plan for future manifest schema evolution |
| INSTALLER-ARCHITECTURE.md | Modders | Installer module map, mod recipes, header convention |
| ODS_CLI_DECOMPOSITION.md | Maintainers / CLI contributors | Behavior-preserving plan for splitting the large Bash operator CLI without a risky rewrite |
| INTEGRATION-GUIDE.md | Developers | Connect apps via OpenAI SDK, LangChain, n8n |
| BACKEND-CONTRACT.md | Developers | Backend runtime contract JSON schema |
| ENGINE-PROVIDER-MODES.md | Maintainers / backend reviewers | Provider mode contract for local, cloud, hybrid, host-native and external-server installs |
| INSTALLER_PHASE_CONTRACTS.md | Maintainers / installer reviewers | Phase ownership, inputs, outputs, idempotency, and validation expectations |
| COMPOSE_RESOLVER_CONTRACTS.md | Maintainers / backend reviewers | Compose layer rules for services, hardware overlays, modes, dependencies, and ports |
| HERMES.md | Developers / operators | Default Hermes Agent packaging, security posture, and operations |
| PIXEL.md | Developers / operators | Pixel eligibility, legal boundary, architecture, default routing, bounded ODS tools, operations, rollback, and qualification |
| OAUTH_PROVIDER_SETUP.md | Operators / maintainers | OAuth provider registry, private credential bundles, and BYOC setup |
| MIGRATION-OPENCLAW-TO-HERMES.md | Operators | Removal notice for the legacy OpenClaw extension: what stays on disk and how to clean it up |
| MIGRATION-LEMONADE-TO-LLAMACPP.md | Operators | AMD GPUs now run on llama.cpp: what an upgrade from Lemonade does, retired settings and options, Vulkan or ROCm, and cleanup |
| Doc | Audience | Description |
|---|---|---|
| HARDWARE-GUIDE.md | Buyers | GPU buying advice, tier recommendations |
| HARDWARE-CLASSES.md | Developers | GPU-to-tier classification logic |
| SUPPORT-MATRIX.md | Operators | Platform/GPU support status |
| MODEL-MANAGEMENT.md | Operators | Curated and Hugging Face GGUF discovery, verified imports, switching, and recovery |
| MODEL-SWITCHBOARD.md | Contributors | Model Switchboard architecture, PR series plan, state/route contracts, and rollout gates |
| CAPABILITY-PROFILE.md | Developers | Machine capability profiling schema |
| MULTI-USER-SETUP.md | Operators | Expose and tune one install for multiple users |
| PROFILES.md | Reference | Docker Compose profiles (historical reference) |
| MODE-SWITCH.md | Operators | Cloud/local/hybrid deployment modes (planned) |
| VLLM-SETUP.md | Operators | Optional vLLM setup notes for high-concurrency NVIDIA inference |
| Doc | Audience | Description |
|---|---|---|
| ../FAQ.md | Everyone | Installation and usage FAQ |
| FAQ.md | Everyone | Hardware and requirements FAQ |
| TROUBLESHOOTING.md | Operators | Common issues and fixes |
| INSTALL-TROUBLESHOOTING.md | Operators | Installer-specific issues |
| ODS-DOCTOR.md | Operators | Diagnostic tool usage |
| SUPPORT-BUNDLE.md | Operators | What to collect before asking for help |
| PREFLIGHT-ENGINE.md | Developers | Preflight validation system |
| Doc | Audience | Description |
|---|---|---|
| MACOS-QUICKSTART.md | Operators | macOS Apple Silicon install guide |
| Doc | Audience | Description |
|---|---|---|
| WINDOWS-QUICKSTART.md | Operators | Windows install guide |
| WINDOWS-INSTALL-WALKTHROUGH.md | Operators | Detailed Windows walkthrough |
| WINDOWS-TROUBLESHOOTING-GUIDE.md | Operators | Windows-specific issues |
| WSL2-GPU-PASSTHROUGH.md | Operators | WSL2 GPU setup |
| WSL2-GPU-TROUBLESHOOTING.md | Operators | WSL2 GPU issues |
| WINDOWS-WSL2-GPU-GUIDE.md | Operators | Combined WSL2 GPU guide |
| DOCKER-DESKTOP-OPTIMIZATION.md | Operators | Docker Desktop tuning |
| Doc | Audience | Description |
|---|---|---|
| M1-OFFLINE-MODE.md | Operators | Air-gapped operation guide |
| SETUP-CARD.md | Operators / hardware builders | Generate printable QR setup cards for headless devices |
| POST-INSTALL-CHECKLIST.md | Operators | Post-install verification |
| KNOWN-GOOD-VERSIONS.md | Operators | Tested image/version combos |
| PLATFORM-TRUTH-TABLE.md | Developers | Platform feature matrix |
| RELEASE_VALIDATION.md | Operators / release reviewers | User Green gates and when operational changes require release-grade fleet validation |
| RELEASE_NOTES_3.0.0.md | Operators / release reviewers | Published V3 source identity and qualification boundaries |
| RELEASE_NOTES_2.6.0.md | Operators / release reviewers | Historical 2.6 release notes, validation receipt, and known validation boundaries |
| VALIDATION-MATRIX.md | Operators / release reviewers | Sanitized CI, distro lab, and real-hardware fleet release-readiness evidence |
| HIGH_RISK_CHANGE_MAP.md | Contributors / maintainers | Risk levels and required validation by changed surface |
| Doc | Audience | Description |
|---|---|---|
| ../CONTRIBUTING.md | Contributors | How to contribute |
| MAINTAINER_RUNBOOK.md | Maintainers / fork operators | Release, rollback, validation, and operator continuity runbook |
| AI_WORKFLOW_GUARDRAILS.md | Contributors / maintainers | Policy for AI-assisted PRs, protected paths, and the requirements for reintroducing AI automation (retired 2026-10-03) |
| BRANCH_HYGIENE.md | Maintainers | Branch naming, stale branch dry-run audits, and cleanup policy |
| ../SECURITY.md | Everyone | Security guide and disclosure |
| ../../SECURITY_AUDIT.md | Maintainers / reviewers | Historical security audit with current remediation status and receipts |
| ../CHANGELOG.md | Everyone | Version history |
| OSS-LAUNCH-CHECKLIST.md | Maintainers | Open-source launch tasks |