Halo

# Halo

[![npm](https://img.shields.io/npm/v/@turmind/halo?color=cb3837&logo=npm)](https://www.npmjs.com/package/@turmind/halo)
[![license](https://img.shields.io/npm/l/@turmind/halo?color=blue)](LICENSE)
[![node](https://img.shields.io/badge/node-%3E%3D22-43853d?logo=node.js&logoColor=white)](https://nodejs.org)

[English](README.md) | [中文](README.zh-CN.md)

**Throw in an idea. A team of agents builds it.**

A self-hosted AI agent team that works in your project folder. Bring your own model key and drive it from a browser, Slack, Telegram or the terminal. A primary agent breaks the work down and fans it out to sub-agents that run in parallel; every tool call shows up live, and you can interrupt, redirect or take over at any point. Everything the team knows and produces is plain files in the workspace — no hidden memory, no opaque state.

![Halo admin — a landing page assembled by parallel sub-agents, previewing live in Canvas](assets/workspace-hero.jpg)
<p align="center"><sub>One prompt — <i>“Build a landing page for our coffee roastery… split the sections across sub-agents in parallel, then assemble.”</i> Executors fan out, report back, and the assembled page previews in Canvas, all in one browser tab.</sub></p>

https://github.com/user-attachments/assets/45f86359-2d83-4c61-b937-0747b184340e

<p align="center"><sub>One real run in 83 seconds: one prompt → the primary agent reads the brief, plans and starts four executors in parallel → Halo City shows the same run as a pixel town → the executors report back and the primary agent assembles the page, previewed in Canvas. 2 h 06 min of real time from prompt to done; sped-up and skipped stretches are marked on screen.</sub></p>

## Install

Halo runs on Linux (x64 / arm64), macOS and Windows, and needs **Node.js 22+**. Ubuntu 24.04's own `nodejs` package is 18 and won't work (`halo` refuses to start on it), so get 22 first:

```bash
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - && sudo apt-get install -y nodejs   # Ubuntu / Debian
brew install node@22           # macOS (keg-only: add it to PATH as brew prints)
nvm install 22                 # with nvm (or: fnm install 22)
```

```bash
npm install -g @turmind/halo   # one binary, all subcommands
halo setup                     # interactive: password / port / model keys / optional skills
halo server start              # → open http://localhost:9527
```

Bring any one model key — Anthropic, OpenAI (or any OpenAI-compatible endpoint), Gemini, DeepSeek, Kimi, Qwen… An AWS account is **not** required; Bedrock is just one of the [providers](#models) (and can use your AWS credential chain instead of a key).

- **`sudo`**: with a system-wide Node (apt / NodeSource), `npm install -g` needs `sudo`; with nvm / fnm it doesn't.
- **In `halo setup`**: at *Configure model provider keys now?* pick **Configure…** (the default). Pick your provider and paste the key, choose **── Done** (the last row; ↑ wraps to it), then press Enter on *Switch default agent to …*.
- **On a remote box**: run `halo server start -d` (plain `start` stays in the foreground and dies with your SSH session; on Linux with systemd, `-d` installs a user service that starts at boot), tunnel with `ssh -L 9527:localhost:9527 user@host`, and open `http://localhost:9527` on your machine. Don't open 9527 in a security group — see [Status & Limitations](#status--limitations).
- **Linux sandbox**: the `workspace` / `readonly` access levels need `sudo apt install bubblewrap`, and on Ubuntu 23.10+ / 24.04 also an [AppArmor profile](.halo/docs/dev/deploy.md#bubblewrap-on-ubuntu-2310-and-2404-apparmor). Without it the server warns at startup with the fix, `/api/health` shows `sandbox: null`, and non-full sessions can't run shell.
- **Upgrade**: `halo upgrade && halo server restart`. A server under systemd restarts through `systemctl`; a system unit ([deploy.md Option C](.halo/docs/dev/deploy.md#option-c-systemd-for-the-npm-install)) may need `sudo systemctl restart halo`. Bundled docs, agents and skills refresh on the next start.
- **Docker / CI**: `halo setup --non-interactive` with `HALO_DEFAULT_PROVIDER=deepseek` and `DEEPSEEK_API_KEY` set binds the built-in agents and writes the key's `<<DEEPSEEK_API_KEY>>` placeholder (never the key) into `~/.halo/secrets/settings.yaml`; keep the variable set for the server too ([deploy.md](.halo/docs/dev/deploy.md#non-interactive-docker--ci-details)). `HALO_PASSWORD` is the *admin* password only.
- **From source**: `pnpm install && pnpm build` (pnpm 11).

**Desktop app**: [GitHub releases](https://github.com/turmind/halo-agent/releases) carry a Windows x64 `.exe` and a macOS Apple Silicon `.dmg` (not every release has both) that bundle the server, admin and their own Node runtime — no `npm`, same `~/.halo/` data, so you can switch later. They're unsigned (macOS "damaged" → `sudo xattr -dr com.apple.quarantine /Applications/Halo.app`; Windows SmartScreen may warn).

> [!IMPORTANT]
> **First message fails with `

... (truncated)