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

> Install Osmantic Deployment System ODS effortlessly on Linux macOS or Windows with Docker. Our guide covers GPU detection and AI stack configuration for a seamless setup.

- Repository: [Osmantic/ODS](https://github.com/Osmantic/ODS)
- Tags: getting-started
- Published: 2026-09-01

---

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

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

```

This command downloads the latest [`install.sh`](https://github.com/Osmantic/ODS/blob/main/install.sh) from the repository, which sources [`install-core.sh`](https://github.com/Osmantic/ODS/blob/main/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`](https://github.com/Osmantic/ODS/blob/main/installers/lib/detection.sh) and [`installers/lib/tier-map.sh`](https://github.com/Osmantic/ODS/blob/main/installers/lib/tier-map.sh), then pulls the appropriate GGUF model using [`scripts/select-model.py`](https://github.com/Osmantic/ODS/blob/main/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:

```powershell
$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`](https://github.com/Osmantic/ODS/blob/main/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:

```bash
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`](https://github.com/Osmantic/ODS/blob/main/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:

```powershell
.\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`](https://github.com/Osmantic/ODS/blob/main/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`](https://github.com/Osmantic/ODS/blob/main/scripts/select-model.py) then queries [`config/model-library.json`](https://github.com/Osmantic/ODS/blob/main/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`](https://github.com/Osmantic/ODS/blob/main/scripts/resolve-compose-stack.sh). This script merges the base definitions in [`docker-compose.base.yml`](https://github.com/Osmantic/ODS/blob/main/docker-compose.base.yml) (containing Open WebUI and llama-server services) with GPU-specific overlays like [`docker-compose.nvidia.yml`](https://github.com/Osmantic/ODS/blob/main/docker-compose.nvidia.yml) or [`docker-compose.apple.yml`](https://github.com/Osmantic/ODS/blob/main/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`](https://github.com/Osmantic/ODS/blob/main/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:**

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

```

**Windows:**

```powershell
$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`](https://github.com/Osmantic/ODS/blob/main/installers/lib/detection.sh) and maps it to a performance tier via [`tier-map.sh`](https://github.com/Osmantic/ODS/blob/main/tier-map.sh) to select appropriate AI models.
- **Manual installation** involves cloning the `Osmantic/ODS` repository and executing [`./install.sh`](https://github.com/Osmantic/ODS/blob/main/./install.sh) directly, giving full control over the 13-phase installation pipeline defined in [`install-core.sh`](https://github.com/Osmantic/ODS/blob/main/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`](https://github.com/Osmantic/ODS/blob/main/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`](https://github.com/Osmantic/ODS/blob/main/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`](https://github.com/Osmantic/ODS/blob/main/./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`](https://github.com/Osmantic/ODS/blob/main/installers/lib/tier-map.sh) (or the PowerShell equivalent on Windows), then invokes [`scripts/select-model.py`](https://github.com/Osmantic/ODS/blob/main/scripts/select-model.py) to query [`config/model-library.json`](https://github.com/Osmantic/ODS/blob/main/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>`.