Installation

Install the Locus CLI and optional Telegram bot package.

Prerequisites

Before installing Locus, make sure you have:

• Node.js 18+ — Download Node.js

• Git — Download Git

• A Locus account — Sign up at app.locusai.dev

• An AI provider CLI — Either Claude CLI or Codex CLI

You need at least one AI provider installed. Locus uses Claude (Anthropic) or Codex (OpenAI) to execute tasks. You can switch between them at any time.

---

Install the CLI

npm

npm install -g @locusai/cli

pnpm

yarn

bun

Verify the installation:

locus --help

You should see the Locus help output listing all available commands.

---

Install the Telegram Bot (Optional)

If you want to control Locus from Telegram, install the bot package separately:

npm install -g @locusai/telegram

Verify:

locus-telegram --help

The Telegram bot is a long-running process — it stays connected to Telegram and executes commands on your behalf. See the Telegram Setup Guide for configuration details.

---

Run Without Installing

You can use npx to run Locus without a global installation:

npx @locusai/cli init
npx @locusai/cli config setup
npx @locusai/cli run

npx downloads the package each time. For regular use, a global install is recommended.

---

Automated Server Setup

For deploying Locus on a server (Linux or macOS), use the interactive installer:

curl -fsSL https://locusai.dev/install.sh | bash

The script will prompt you for your repository URL, API key, GitHub token, and optional Telegram configuration. It installs all dependencies, configures services, and sets up automatic agent execution. See Self-Hosting for full details.

---

Next Steps

Once installed, you need to:

1. Set up your workspace — Create a workspace and get your API key

2. Initialize your project — Run locus init in your repository