Install

CLIO is a backend plus workspace interfaces (a desktop app, a web page, and a terminal UI). Pick the install path that matches how you want to use it. All of them end in the same place: a CLIO backend running on your machine and an interface connected to it.

Desktop app

Download the installer for your system from the latest release. The desktop app updates itself from the same release page.

Under Settings → Desktop → App updates, turn on Enable beta updates to receive published beta releases for both Desktop and the Agent. Betas may be unstable. With the switch off, only stable releases are offered; changing the setting never installs an update or downgrades your current version. Existing beta installations keep the beta channel unless you explicitly turn it off.

Desktop beta 1 predates this setting and needs one manual Desktop upgrade to receive channel-aware updates. A GitHub draft is still being prepared and is excluded from both channels; a published pre-release is available to beta users.

Each platform comes in one or two variants:

• Bundled installers (-bundled in the file name) include the CLIO backend. There is nothing else to install.
• Attach-only installers are much smaller than bundled ones (about 10 to 20 MB, except the AppImage at about 100 MB) and connect to a CLIO backend that you install and run separately, for example with the install script or uv.

Platform	Bundled	Attach-only
Windows x64	.exe (setup) and .msi	.exe (setup) and .msi
Windows on ARM	none	.exe
macOS 14+, Apple Silicon	.dmg	.dmg
macOS 14+, Intel	none	.dmg
Linux x86_64 and aarch64	.deb and .rpm	.deb, .rpm, and .AppImage

When you close the window, the app asks “Keep CLIO running?” You can keep it running in the system tray or quit. The app runs as a single instance.

Desktop lets you connect to an existing CLIO service or deploy a separate one. Use the existing-service option when you already run CLIO from a terminal.

Install Desktop from a terminal

These commands install the Desktop application and verify its release SHA-256 checksum. They require no Python, uv, or Node installation. To try beta 3 explicitly:

macOS

curl -fsSL https://raw.githubusercontent.com/iowarp/clio-agent/main/install/desktop.sh \
  | CLIO_VERSION=v0.9.5-beta.3 bash

Installs into ~/Applications, retaining a previous app beside it when upgrading. Apple Silicon receives the bundled backend; Intel receives an attach-only app. Set CLIO_DESKTOP_DIR to choose another absolute application directory.

Windows

$env:CLIO_VERSION = 'v0.9.5-beta.3'
irm https://raw.githubusercontent.com/iowarp/clio-agent/main/install/desktop.ps1 | iex

Runs the bundled x64 setup silently and adds CLIO Desktop to the Start menu. Windows on ARM uses x64 emulation.

Omit CLIO_VERSION to select the latest stable release. The macOS script requires an intact signed app and refuses older unsigned packages. Use --download-only DIR with the saved shell script, or -DownloadOnly -DownloadDirectory DIR with the saved PowerShell script, to verify a download without installing it.

macOS first launch

CLIO currently uses an ad-hoc app signature, not Apple Developer ID notarization. If macOS asks for approval, open System Settings → Privacy & Security → Open Anyway after attempting to open the app. The installer does not change Gatekeeper or remove quarantine attributes. An invalid signature or failed checksum is an installation error; do not bypass it.

On Linux, choose the bundled .deb or .rpm for a local backend. The AppImage is attach-only and needs a separately installed service.

Install script

The script installs the backend, a terminal UI, a web UI bundle, and the clio command. It needs curl (or PowerShell on Windows), plus either uv or Python 3.13 with pip. It does not need git or Go.

macOS and Linux

curl -fsSL https://raw.githubusercontent.com/iowarp/clio-agent/main/install/install.sh | bash

Run it under bash, not sh. Unpacking the web bundle needs unzip. If that step fails, the installer warns and clio --web is disabled.

Windows

irm https://raw.githubusercontent.com/iowarp/clio-agent/main/install/install.ps1 | iex

Then start CLIO:

clio

The first start is slower than later ones. See Connect a model for the next step.

What it installs and where

Item	macOS and Linux	Windows
Install prefix	Linux: $XDG_DATA_HOME/clio-agent/app (default ~/.local/share/clio-agent/app); macOS: ~/Library/Application Support/clio-agent/data/app	%LOCALAPPDATA%\clio-agent\data\app
clio command	~/.local/bin/clio	clio.cmd and clio.ps1 in %LOCALAPPDATA%\Microsoft\WindowsApps

Inside the prefix:

• The clio-agent backend from PyPI, in its own virtual environment at clio-agent/.venv.
• The terminal UI binary for your OS and architecture.
• The web UI bundle, unpacked to clio-agent/web.
• An uninstall script.

If uv is present, the script also installs clio-kit (version 2.10.6) as a uv tool. Marketplace blueprints use it to launch their tool servers. Without uv, the script warns and skips this step. Install uv, run uv tool install clio-kit==2.10.6, and make sure the folder printed by uv tool dir --bin is on your PATH.

Script environment variables

Set these before running the script.

Variable	Effect
CLIO_PREFIX	Install root.
CLIO_BIN_DIR	Where the clio command goes.
CLIO_VERSION	Install a specific release. Use the PyPI version with no leading v, for example 0.9.4.24.
CLIO_REF	A branch or tag. Builds from source instead of downloading a release, and needs git, uv, and Go 1.26 or newer.

macOS and Linux

curl -fsSL https://raw.githubusercontent.com/iowarp/clio-agent/main/install/install.sh \
  | CLIO_VERSION=0.9.4.24 bash

Windows

$env:CLIO_VERSION = '0.9.4.24'
irm https://raw.githubusercontent.com/iowarp/clio-agent/main/install/install.ps1 | iex

Use the same CLIO_PREFIX and CLIO_BIN_DIR when you uninstall.

Docker

Three images are published to the GitHub Container Registry on each release, tagged with the version and latest.

Image	What it is	Run it
ghcr.io/iowarp/clio-web	Backend plus the web UI	docker run --rm -p 8080:80 ghcr.io/iowarp/clio-web:latest, then open http://localhost:8080
ghcr.io/iowarp/clio-api	Headless backend on port 8100, for scripts and other clients	docker run --rm -p 8100:8100 ghcr.io/iowarp/clio-api:latest
ghcr.io/iowarp/clio-tui	The terminal UI with a bundled backend; needs a terminal (-it)	See below

docker run -it --rm \
  -e CLIO_LM_API_BASE=http://host.docker.internal:1234/v1 \
  ghcr.io/iowarp/clio-tui:latest

Docker Compose

The repository’s docker-compose.yml runs the published images:

docker compose up clio-web          # web UI at http://localhost:8080
docker compose --profile api up     # headless backend on port 8100

Point CLIO at your model with environment variables. The defaults assume LM Studio on the host machine.

Variable	Default
CLIO_LM_PROVIDER	lm_studio
CLIO_LM_API_BASE	http://host.docker.internal:1234/v1
CLIO_LM_MODEL	empty (use the loaded model)
CLIO_LM_API_KEY	lm-studio

Saved data lives in the clio-data volume, mounted at /home/clio/.config/clio-agent.

If you open the web UI by a name other than localhost, such as a LAN address or host name, list that name in CLIO_GACT_ALLOWED_HOSTS (host names only, no ports, comma-separated). Otherwise requests are refused with host_not_allowed.

Backend only with uv

If you only want the backend, for example to serve the API or to attach a desktop app, install it as a persistent uv tool:

uv tool install --python 3.13 --with dspy==3.3.0b1 --with fastmcp==4.0.0b5 --with fastmcp-slim==4.0.0b5 --with fastmcp-tasks==4.0.0b5 clio-agent==0.9.4.24
clio-agent serve

The extra --with pins are required: CLIO depends on specific prerelease versions of two libraries, and uv needs them named explicitly. Use uv tool upgrade clio-agent to upgrade later. This path does not include the terminal UI or the clio command.

From source

git clone --recurse-submodules https://github.com/iowarp/clio-agent
cd clio-agent
uv sync --extra optimizers --extra argonne
uv run clio-agent serve

See Contributing for the development workflow.

Next steps

Connect a modelChoose where CLIO gets its language model.

Command lineStart, stop, and inspect CLIO from a terminal.