# CLAI — full reference

> CLAI is a free, open-source (MIT) desktop app for macOS, Windows, and Linux that lets you control teams of AI agents. Local-first, open source, sandboxed. One team per workspace — every agent with its own provider, files, tools, and permissions, working in parallel, on your schedule, and reporting to you from one Fleet cockpit.

Last updated: 2026-10-16

- Website: https://clai.run/
- Download: https://clai.run/download/
- Source code: https://github.com/clairun/clai
- Latest release (current version number and release notes): https://github.com/clairun/clai/releases/latest
- License: MIT — https://github.com/clairun/clai/blob/main/LICENSE
- Contact: hello@clai.run
- Community: https://github.com/clairun/clai/discussions

This file is meant to be complete: an assistant should be able to answer questions about CLAI from it alone. Version numbers are intentionally not listed here; the latest release page is the source of truth for the current version.

## What CLAI is

CLAI is a desktop application ("CLAI Desktop") for running and supervising AI agents on your own machine. It organizes work into **workspaces**. A workspace is an ongoing conversation with a **main agent** — a configurable LLM that owns the workspace's provider, tools, skills, and permissions. The main agent can:

- **Chat** with you in a surface that stays front and center.
- **Use tools** through attached MCP servers and a local shell sandbox.
- **Delegate** to helper agents in the same workspace, each with their own skills, tools, and execution policy.
- **Persist context** — memories and artifacts it writes are inspectable from the workspace header.
- **Run on a schedule** — periodic workspaces fire on their schedule (interval or cron).

The **Fleet** view supervises everything: scheduled workspaces float to the top, anything needing attention (failed or blocked tasks, input prompts) is flagged, and selecting a card slides in a live chat preview.

## Core concepts

- **Workspace** — A project or recurring task. It owns its main agent, its team of helper agents, its history (a persistent session), its schedule, its memory, and its files. Each workspace has its own directory on disk where agents write memories and artifacts.
- **Main agent** — The agent you chat with in a workspace. It owns the workspace's provider, MCP servers, skills, and permissions, and can delegate to helpers.
- **Helper agents (teammates)** — Additional agents in a workspace, for example a Code Reviewer, a researcher, or an operations agent. Each has its own instructions, skills, MCP servers, provider, and execution policy. The main agent calls them as tools, and you can read their full transcripts.
- **Shared agent library** — Teammates are defined once in Settings → *Agents* and added to the workspaces that need them. Editing one reaches every workspace using it, from its next turn. Each workspace still owns its own main agent, history, and schedule, and keeps local settings for a teammate: whether it is enabled there, the context it works under, and the paths it may touch.
- **Fleet** — The cockpit that supervises all workspaces. Scheduled workspaces float to the top; failed or blocked tasks and pending input prompts are flagged; selecting a card shows a live chat preview.
- **Tasks** — Delegated work. Each task streams a live transcript: the helper agent's full conversation, tool calls, and verdict.
- **Schedules** — A workspace can run its main agent periodically: at a fixed interval of 1 to 1440 minutes, or on a cron expression (presets such as Hourly, Daily 9am, and Daily midnight) evaluated in the workspace's timezone. The timezone and the preview of the next run times before saving apply to cron schedules only. Scheduled runs emit the same streaming events as interactive chat, and their outputs, transcripts, and artifacts stay attached to the workspace.
- **Skills** — Reusable instruction sets discovered from read-only local or Git sources and attached to agents where they help. CLAI registers the read-only `clairun/clai-skills` repository (https://github.com/clairun/clai-skills) by default.
- **Memory and artifacts** — Agents persist findings to the workspace directory. A drawer surfaces both, with read-only previews (rendered Markdown, pretty JSON, multi-file HTML).
- **MCP (Model Context Protocol)** — CLAI is an MCP client. Configure MCP servers once in Settings (HTTP and stdio transports; static credentials or OAuth), then attach them per workspace or per agent.
- **Local execution sandbox** — Each agent has filesystem grants (paths it may read or read/write) and one of three shell modes:
  - **Off** — no generic local file access.
  - **Restricted** — only allowed command prefixes run. For example, an allowed prefix `kubectl get` permits `kubectl get pods` but not `kubectl delete`.
  - **Full** — any command not blocked.
- **Filesystem grants** — Per-agent paths an agent may access, read-only or read-write. Grants are additive. An "always allow" for a command is saved on the shared agent; a path grant approved during a run is saved on the workspace's local assignment, so approving it in one workspace never widens access in another.
- **Run notices** — A run that hits a policy denial finishes in an amber "warnings" state and surfaces in the Fleet instead of failing silently.

## Sandbox by platform

Local execution sandboxing is platform-specific:

- **Linux** — shell commands run through bubblewrap.
- **macOS** — shell commands run through Seatbelt via `sandbox-exec`.
- **Windows** — there is no sandbox backend. Shell execution is labeled as a host shell; CLAI still validates the command's working directory against the filesystem grants, but nothing stops the command itself from reaching outside them. Windows ships no POSIX shell, so the shell tool looks for Git Bash, then MSYS2, then `bash` on `PATH`, and asks you to install Git for Windows when it finds none.

The command allow/block lists are enforced by CLAI before a command spawns, on every platform.

## Features

- **Workspace-local agent teams** — Add helpers (e.g. a Code Reviewer) with their own prompts, skills, MCP servers, providers, and execution policy. The main agent calls them as tools, and you can read their full transcripts.
- **Multiple providers** — API connections (OpenAI-compatible or Anthropic-compatible) and local CLI agents such as Claude Code, OpenAI Codex, and OpenCode. Each agent picks its own.
- **Local and hosted models** — Local presets (Ollama, LM Studio, vLLM, LiteLLM) and hosted OpenAI-compatible and Anthropic-compatible providers.
- **MCP-native tools** — Configure MCP servers once in Settings, then attach them per workspace or per agent. HTTP and stdio transports; static credentials or OAuth.
- **Local execution sandbox** — Per-agent filesystem grants and three shell modes: Off, Restricted, and Full.
- **Shared agent library** — Define teammates once in Settings → Agents and add them to any workspace.
- **Scheduled workspaces** — A fixed interval (1 to 1440 minutes) or a cron expression evaluated in the workspace's timezone, with a next-run preview for cron.
- **Skills** — From default (`clairun/clai-skills`), local, or Git-backed sources.
- **Inspectable tasks** — Delegated work streams a live transcript of the helper's conversation, tool calls, and verdict.
- **Memory and artifacts** — Generated files, task transcripts, and durable memories stay next to the workspace that produced them.
- **Run notices** — Policy denials surface as amber warnings in the Fleet.
- **Fleet cockpit** — One view of agent messages, tool calls, delegated tasks, files, memory, and generated artifacts.
- **Updates** — macOS and Windows builds update themselves. On Linux, .deb/.rpm and Flatpak installs show when an update is available; install it with apt/dnf or `flatpak update`. AUR installs don't check; update with your AUR helper.

## Supported providers

Each agent chooses its own provider, so you can mix them — for example a Claude Code main agent with an OpenAI-compatible reviewer.

- **API connections** — Add an **OpenAI-compatible** or **Anthropic-compatible** provider with an API key and optional custom base URL. Works with OpenAI, Anthropic, together.ai, Groq, and local endpoints (vLLM, llama.cpp, Ollama). The provider picker also has presets for LM Studio and LiteLLM.
- **CLI agents** — Drive a locally installed coding CLI directly: **Claude Code**, **OpenAI Codex**, or **OpenCode**. CLAI exposes its tools to them over MCP and streams their output like any other run. CLI-backed agents can use your existing subscription login. Supported CLI agents are auto-detected and pre-wired into new workspaces.

## Install

Download the latest build for your platform from https://clai.run/download/ or the Releases page (https://github.com/clairun/clai/releases/latest).

| Platform   | Download |
|------------|----------|
| Windows    | `.msi` / `.exe` |
| macOS      | `.dmg` |
| Linux      | `.deb`, `.rpm`, or `.flatpak` |
| Arch Linux | AUR: `clai-desktop-bin` (https://aur.archlinux.org/packages/clai-desktop-bin) |

### Direct download links (always the latest release)

- macOS, Apple Silicon (M1, M2, M3, M4): https://download.clai.run/latest/clai_aarch64.dmg
- macOS, Intel (x86_64): https://download.clai.run/latest/clai_x64.dmg
- Windows installer (.exe, recommended): https://download.clai.run/latest/clai_x64-setup.exe
- Windows MSI (for managed installs): https://download.clai.run/latest/clai_x64_en-US.msi
- Linux, Debian/Ubuntu (.deb): https://download.clai.run/latest/clai_amd64.deb
- Linux, Fedora/openSUSE (.rpm): https://download.clai.run/latest/clai.x86_64.rpm
- Linux, any distro (Flatpak): https://download.clai.run/latest/clai.flatpak

System requirements listed on the download page: macOS 11 or later; Windows 10 or later, 64-bit; Linux x86_64. Updater signatures (.sig) and every previous version are on GitHub Releases. Android and iOS companions are planned but not available yet.

### Debian / Ubuntu (apt repository)

Updates then arrive through `apt upgrade` like any other package:

```bash
sudo curl -fsSLo /usr/share/keyrings/clai-archive-keyring.gpg \
  https://download.clai.run/apt/clai-archive-keyring.gpg
echo "deb [arch=amd64 signed-by=/usr/share/keyrings/clai-archive-keyring.gpg] https://download.clai.run/apt stable main" | \
  sudo tee /etc/apt/sources.list.d/clai.list
sudo apt update && sudo apt install clai
```

### Fedora / RHEL (dnf repository)

Updates then arrive through `dnf upgrade`:

```bash
sudo curl -fsSLo /etc/yum.repos.d/clai.repo https://download.clai.run/rpm/clai.repo
sudo dnf install clai
```

### openSUSE (zypper)

```bash
sudo zypper ar -f https://download.clai.run/rpm clai && sudo zypper install clai
```

Installing the `.deb`/`.rpm` from the Releases page enrolls the same repository automatically (see `packaging/linux-repo/README.md` in the source repository, including the opt-outs).

### Arch Linux (AUR)

```bash
yay -S clai-desktop-bin
```

### macOS: "clai is damaged and can't be opened"

The macOS builds are not yet signed or notarized with an Apple Developer ID, so after downloading macOS may say "clai is damaged and can't be opened". The app is not damaged. Move `clai.app` to Applications, run this once in Terminal to remove the download quarantine flag, then open it normally:

```bash
xattr -cr /Applications/clai.app
```

## Getting started

1. **Add a provider** — In Settings, connect an API provider or point CLAI at a local CLI agent. Supported CLI agents are auto-detected and pre-wired into new workspaces.
2. **Add MCP servers (optional)** — Register local or remote MCP servers for external tools.
3. **Create a workspace** — From the Fleet view. Open its settings (gear icon in the header) to attach a provider, MCP servers, and skills.
4. **Chat** with the main agent.
5. **Add helper agents (optional)** — Define them once in Settings → *Agents*, then add them to a workspace's team from its settings; the main agent can then delegate to them.
6. **Make it periodic (optional)** — Toggle *Schedule* to run the main agent on a schedule (interval or cron).

## Architecture

- **Frontend** — React + Tauri; a chat-first workspace with a drawer for agents / tasks / memories / artifacts and slide-out transcript and file panels.
- **Runtime** — Each workspace owns its main agent, its assignments of shared agents, and a persistent session. Built-in tools (shell execution, inter-agent calls, task management) plus MCP tools, gated by each agent's policy. An agent is resolved fresh at the start of every turn, so a shared edit lands on the next turn and never mid-tool-sequence.
- **Scheduler** — Periodic workspaces run from the agent runner, emitting the same streaming events as interactive chat.
- **Skills** — Discovered from read-only local or git sources. The app-managed default source is `clairun/clai-skills`.

To build from source:

```bash
git clone https://github.com/clairun/clai.git
cd clai
npm install
make dev            # run the desktop app in development
```

## FAQ

The first nine answers match the FAQ on https://clai.run/#faq.

### What is CLAI?
CLAI is a free, open-source desktop app for controlling teams of AI agents. You create workspaces; each has a main agent you chat with and optional helper agents it can delegate to. Every agent has its own model provider, files, tools, and permissions, and the Fleet view shows what every workspace is doing.

### Is CLAI free and open source?
Yes. CLAI Desktop is free and MIT licensed, and it is developed in the open at github.com/clairun/clai.

### Which platforms does CLAI run on?
macOS 11 or later (Apple Silicon and Intel), Windows 10 or later (64-bit), and Linux x86_64 as .deb, .rpm, Flatpak, or the AUR package clai-desktop-bin. Android and iOS companions are planned but not available yet.

### Which models and providers does CLAI support?
Any OpenAI-compatible or Anthropic-compatible API, including OpenAI, Anthropic, together.ai, Groq, and local endpoints such as Ollama, LM Studio, vLLM, and llama.cpp. CLAI can also drive locally installed CLI agents: Claude Code, OpenAI Codex, and OpenCode. Each agent picks its own provider.

### Does CLAI run locally? Where does my data go?
CLAI is a local-first desktop app. Workspaces, memories, and artifacts are stored in workspace directories on your machine. Prompts are sent to the model provider you configure for each agent; with a local model they stay on your machine, unless an agent uses the built-in web search/fetch tools or remote MCP servers, which send their requests to those services.

### What is a workspace, and what is the Fleet?
A workspace is an ongoing conversation with a main agent that owns its provider, tools, skills, and permissions, plus any helper agents on its team. The Fleet view supervises all workspaces: scheduled ones float to the top, and failed or blocked tasks and input prompts are flagged.

### Can agents run on a schedule?
Yes. Toggle Schedule in a workspace's settings to run its main agent at a fixed interval (1 to 1440 minutes) or on a cron expression, with presets such as Hourly and Daily 9am. Cron schedules are evaluated in the workspace's timezone and preview the next run times. Outputs, transcripts, and artifacts stay attached to the workspace.

### How are shell commands sandboxed?
Each agent has filesystem grants and one of three shell modes: Off (no generic local file access), Restricted (only allowed command prefixes), or Full. Commands run through bubblewrap on Linux and Seatbelt on macOS. Windows has no sandbox backend: CLAI checks the working directory and the allow/block lists, but the command itself is not contained.

### How do I install CLAI on Linux, macOS, or Windows?
Download the installer for your platform from the download page. On Linux you can also use the apt repository (Debian/Ubuntu), the dnf repository (Fedora/RHEL), zypper (openSUSE), or the AUR (Arch). macOS builds are not yet notarized, so if macOS says the app is damaged, run xattr -cr /Applications/clai.app once in Terminal.

### How do I update CLAI?
macOS and Windows builds update themselves. On Linux, .deb/.rpm and Flatpak installs show when an update is available; install it with apt/dnf or `flatpak update`. AUR installs don't check; update with your AUR helper.

## Links

- Website: https://clai.run/
- Download: https://clai.run/download/
- llms.txt index: https://clai.run/llms.txt
- Source code: https://github.com/clairun/clai
- Releases: https://github.com/clairun/clai/releases
- Latest release: https://github.com/clairun/clai/releases/latest
- Changelog: https://github.com/clairun/clai/blob/main/CHANGELOG.md
- Discussions: https://github.com/clairun/clai/discussions
- Issues: https://github.com/clairun/clai/issues
- AUR: https://aur.archlinux.org/packages/clai-desktop-bin
- Default skills: https://github.com/clairun/clai-skills

## License

CLAI is released under the MIT License: https://github.com/clairun/clai/blob/main/LICENSE

## Contact

Email hello@clai.run for product feedback, MCP integrations, packaging questions, or collaboration, or use GitHub Discussions.