How to Install Osmantic Deployment System (ODS): Complete Setup Guide

You can install ODS on Linux or macOS with a single curl command, or on Windows via PowerShell, requiring only Docker while the installer automatically detects your GPU and configures the appropriate AI inference stack.

The Osmantic Deployment System (ODS) is a self-contained, open-source platform that wires together local LLM inference, chat UIs, voice agents, RAG pipelines, and image generation through a modular Docker architecture. This guide walks through every installation method available in the Osmantic/ODS repository, from one-liner automated scripts to manual source builds.

Prerequisites

Before installing ODS, ensure your system meets these baseline requirements:

• Docker must be installed and actively running. On Windows, this requires Docker Desktop with the WSL2 backend enabled.
• A terminal with standard user privileges (Bash on Linux/macOS, PowerShell on Windows).
• (Optional) GPU drivers for hardware acceleration. ODS auto-detects NVIDIA, AMD Strix Halo, Apple Silicon, and Intel Arc GPUs, falling back to CPU or cloud mode if no local GPU is available.

Automated Installation

ODS provides platform-specific installers that handle GPU detection, model selection, and Docker orchestration automatically.

Linux and macOS One-Liner

The fastest way to install ODS on Unix systems uses the remote installer script:

curl -fsSL https://install.osmantic.com/ods.sh | bash

This command downloads the latest install.sh from the repository, which sources install-core.sh to execute a 13-phase installation pipeline. The installer logic resides in installers/phases/ (from 01-preflight through 13-summary) and uses pure-function libraries in installers/lib/ to ensure idempotent provisioning. The script detects your hardware tier via installers/lib/detection.sh and installers/lib/tier-map.sh, then pulls the appropriate GGUF model using scripts/select-model.py before starting the Docker stack.

Windows PowerShell Installation

For Windows environments, ODS provides a self-contained PowerShell script that mirrors the Linux installer's behavior:

$ProgressPreference = "SilentlyContinue"
$odsSrc = Join-Path $env:TEMP ("ods-install-" + [guid]::NewGuid().ToString("N"))
$odsZip = Join-Path $odsSrc "ods-main.zip"
New-Item -ItemType Directory -Path $odsSrc | Out-Null
Invoke-WebRequest "https://github.com/Osmantic/ODS/archive/refs/heads/main.zip" -OutFile $odsZip
Expand-Archive -LiteralPath $odsZip -DestinationPath $odsSrc -Force
cd (Get-ChildItem -LiteralPath $odsSrc -Directory | Select-Object -First 1).FullName
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\install.ps1

This script downloads the main branch ZIP, extracts it to a temporary directory, and executes install.ps1. The Windows installer leverages installers/windows/lib/tier-map.ps1 for hardware detection and reads config/model-library.json to select compatible models, then configures the Docker Compose stack using the same overlay system as the Linux implementation.

Manual Installation Methods

For users requiring full control over the installation process or working in air-gapped environments, ODS supports manual checkout and execution.

Manual Install on Linux/macOS

Clone the repository and run the installer directly from the source tree:

git clone https://github.com/Osmantic/ODS.git
cd ODS/ods
./install.sh

This approach allows you to inspect the installer phases in installers/phases/ and modify environment variables in .env.example before deployment. The local install.sh executes the same 13-phase pipeline as the curl method, sourcing library functions from installers/lib/ to handle GPU detection and tier mapping.

Manual Install on Windows

After extracting the repository ZIP using the PowerScript commands above (excluding the final .\install.ps1 execution), navigate to the extracted directory and run:

.\installers\windows\ods.ps1

This bypasses the automated download logic while preserving the hardware detection and Docker configuration steps defined in the Windows installer libraries.

How the ODS Installer Works

Understanding the installation architecture helps troubleshoot issues and customize deployments.

Hardware Detection and Model Selection

The installer implements deterministic hardware tiering through installers/lib/detection.sh (or tier-map.ps1 on Windows), which categorizes your system into a performance tier. The Python selector at scripts/select-model.py then queries config/model-library.json to choose an optimal GGUF model for your GPU or CPU configuration. This ensures ODS deploys quantized models appropriate for your hardware capabilities without manual intervention.

Docker Compose Stack Resolution

ODS uses a layered compose architecture orchestrated by scripts/resolve-compose-stack.sh. This script merges the base definitions in docker-compose.base.yml (containing Open WebUI and llama-server services) with GPU-specific overlays like docker-compose.nvidia.yml or docker-compose.apple.yml. The resolver also incorporates extension fragments from extensions/services/<service>/compose.yaml files, generating a final Docker Compose configuration that powers the entire stack.

Extension System and CLI

Each ODS service is packaged as an extension under extensions/services/<name>/ with a manifest.yaml declaring metadata, ports, and GPU backend requirements. After installation, the ods-cli script (located at ods/ods-cli) provides high-level commands such as ods status, ods model swap, and ods enable <service> to manage the Dockerized environment. Configuration persists in a .env file derived from .env.example, allowing you to override ports, model paths, and feature flags.

Verifying Your Installation

Once the installer completes, verify the deployment by accessing the dashboard at http://localhost:3000. The LLM inference endpoint is available at http://localhost:11434 when running under Linux Docker, or http://localhost:8080 for native macOS and Windows builds. Run ods status from the installation directory to confirm all containers are healthy and properly networked.

Uninstalling ODS

To completely remove ODS and associated Docker resources:

Linux/macOS:

cd ~/ods
./ods-uninstall.sh --force

Windows:

$installDir = "$env:USERPROFILE\ods"
cd $installDir
.\ods.ps1 uninstall --force

These scripts remove Docker containers, networks, and volumes labeled with the ODS compose project, then delete the runtime directory without affecting other system configurations.

Summary

• ODS installation requires only Docker and can be completed with a single command on Linux/macOS (curl -fsSL https://install.osmantic.com/ods.sh | bash) or via PowerShell on Windows.
• The installer automatically detects GPU hardware using installers/lib/detection.sh and maps it to a performance tier via tier-map.sh to select appropriate AI models.
• Manual installation involves cloning the Osmantic/ODS repository and executing ./install.sh directly, giving full control over the 13-phase installation pipeline defined in install-core.sh.
• Post-installation, access the dashboard at localhost:3000 and manage the stack using the ods-cli utility, which orchestrates Docker services defined in dynamically resolved compose files.
• Uninstall scripts (ods-uninstall.sh or ods.ps1 uninstall) cleanly remove all ODS Docker resources and runtime directories.

Frequently Asked Questions

What are the system requirements for installing ODS?

ODS requires Docker to be installed and running, with WSL2 enabled on Windows systems. While GPU drivers are optional, having NVIDIA, AMD, Apple Silicon, or Intel Arc drivers installed enables local AI inference; otherwise, ODS falls back to CPU inference or cloud API modes. The installer handles architecture detection automatically through installers/lib/detection.sh.

Can I install ODS without using the automated curl or PowerShell scripts?

Yes, you can perform a manual installation by cloning the repository with git clone https://github.com/Osmantic/ODS.git, navigating to ODS/ods, and running ./install.sh directly. This method is required for offline installations or when customizing the .env configuration file before deployment, as it allows inspection of the installer phases in installers/phases/ before execution.

How does ODS determine which AI model to download during installation?

ODS maps your detected hardware to a deterministic tier using installers/lib/tier-map.sh (or the PowerShell equivalent on Windows), then invokes scripts/select-model.py to query config/model-library.json. This catalog contains quantized GGUF models matched to specific GPU tiers, ensuring ODS deploys a model that balances performance with your hardware capabilities without requiring manual model selection.

Where can I change the default ports or swap models after installing ODS?

Configuration is managed through the .env file in your ODS installation directory, based on the template at .env.example. You can modify ports, model paths, and feature flags there, then apply changes using the ods-cli utility with commands like ods restart or ods model swap. The extension system in extensions/services/<name>/manifest.yaml also allows enabling or disabling specific services via ods enable <service> or ods disable <service>.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}