Skip to content

README.md

Latest commit

 

History

History
189 lines (159 loc) · 15.3 KB

README.md

File metadata and controls

189 lines (159 loc) · 15.3 KB

Dream Server Documentation Index

This is the maintained map for operators, contributors, and reviewers. Links from this directory use ../ for the dream-server/ 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.

Start Here By Job

Use this table as the "you are here" map. Dream Server 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.

I want to... Read this first Then use
Install the default path ../QUICKSTART.md INSTALLER_TRUST.md, SUPPORT-MATRIX.md, POST-INSTALL-CHECKLIST.md
Install on Windows WINDOWS-QUICKSTART.md WINDOWS-INSTALL-WALKTHROUGH.md, WINDOWS-WSL2-GPU-GUIDE.md
Install on Apple Silicon MACOS-QUICKSTART.md MODEL-MANAGEMENT.md, TROUBLESHOOTING.md
Debug a broken install DREAM-DOCTOR.md INSTALL-TROUBLESHOOTING.md, SUPPORT-BUNDLE.md
Change installer behavior INSTALLER-ARCHITECTURE.md BACKEND-CONTRACT.md, PREFLIGHT-ENGINE.md
Change model routing MODEL-MANAGEMENT.md MODE-SWITCH.md, BACKEND-CONTRACT.md
Add or harden a service EXTENSIONS.md ../extensions/CATALOG.md, ../extensions/schema/README.md
Build a custom edition or fork FORKABILITY.md RELEASE_CHANNELS.md, BUILD-ON-DREAM-SERVER.md, OFFLINE_AND_MIRRORING.md, VALIDATION_REPRODUCIBILITY.md
Review a PR ../CONTRIBUTING.md HIGH_RISK_CHANGE_MAP.md, TESTING.md, RELEASE_VALIDATION.md, VALIDATION-MATRIX.md
Maintain a release or fork MAINTAINER_RUNBOOK.md HIGH_RISK_CHANGE_MAP.md, INSTALLER_PHASE_CONTRACTS.md, COMPOSE_RESOLVER_CONTRACTS.md, BRANCH_HYGIENE.md
Review automation guardrails AI_WORKFLOW_GUARDRAILS.md ../CONTRIBUTING.md, HIGH_RISK_CHANGE_MAP.md

Choosing Validation

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.

Document Status

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, RELEASE_VALIDATION.md
Operator guide Helps users install, operate, or troubleshoot ../QUICKSTART.md, DREAM-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, DREAM_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

Current Truths

  • 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.
  • The default agent path is Hermes Agent plus hermes-proxy. OpenClaw remains available for compatibility, but it is deprecated and no longer enabled by default.
  • Linux Docker installs expose llama-server on host OLLAMA_PORT=11434 by default while containers use llama-server:8080. macOS native Metal and Windows native/Lemonade paths use host port 8080 unless overridden.
  • Windows installs should run from a normal user PowerShell, not Administrator. The default install directory is $env:USERPROFILE\dream-server unless DREAM_HOME is set.
  • Bundled service truth lives in extensions/services/*/manifest.yaml. Core host-facing port defaults are tracked in config/ports.json; per-service manifest defaults live with each service. The dashboard extension library catalog is generated into config/extensions-catalog.json.
  • Generated runtime config has several writers. If you change .env, OpenCode, Perplexica, Hermes, or LiteLLM/Lemonade behavior, update the Linux, macOS, Windows, bootstrap-upgrade, and host-agent paths together.

Getting Started

Doc Audience Description
HOW-DREAM-SERVER-WORKS.md Everyone The friendly guide — what Dream Server 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

Building & Extending

Doc Audience Description
BUILD-ON-DREAM-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
../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
DREAM_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
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
OAUTH_PROVIDER_SETUP.md Operators / maintainers OAuth provider registry, private credential bundles, and BYOC setup
OPENCLAW-INTEGRATION.md Developers Deprecated OpenClaw setup and migration reference

Hardware & Configuration

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 Dashboard model downloads, switching, and manual GGUF workflows
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

Troubleshooting

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
DREAM-DOCTOR.md Operators Diagnostic tool usage
SUPPORT-BUNDLE.md Operators What to collect before asking for help
PREFLIGHT-ENGINE.md Developers Preflight validation system

macOS

Doc Audience Description
MACOS-QUICKSTART.md Operators macOS Apple Silicon install guide

Windows

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

Operations

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
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

Project

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 Maintainers / reviewers Safety model for AI-assisted GitHub workflows, protected paths, and human review boundaries
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
COMPOSABILITY-EXECUTION-BOARD.md Maintainers Internal project tracking
OSS-LAUNCH-CHECKLIST.md Maintainers Open-source launch tasks