Installation

Install the Locus CLI, GitHub CLI, and an AI provider CLI (Claude Code or Codex).

Prerequisites

Locus requires three baseline tools, plus Docker Desktop for sandboxed execution:

Requirement	Minimum Version	Purpose
Node.js	18+	Runtime for the CLI
GitHub CLI (gh)	Latest	All GitHub operations (issues, PRs, milestones)
AI Provider CLI	Latest	Task execution and code generation
Docker Desktop	4.58+	Sandbox isolation for safe AI execution (docker sandbox)

You need one of the following AI provider CLIs installed:

• Claude Code (Anthropic) -- default provider

• Codex (OpenAI)

---

Install the CLI

npm

npm install -g @locusai/cli

pnpm

yarn

bun

Verify the installation:

locus --version

---

Set Up GitHub CLI

Locus uses the GitHub CLI (gh) for every GitHub interaction -- creating issues, milestones, labels, and pull requests. Install and authenticate it before proceeding.

Install gh

macOS

brew install gh

Linux

Windows

Authenticate

gh auth login

Follow the interactive prompts to authenticate with your GitHub account. When finished, verify:

gh auth status

You should see output confirming you are logged in.

Locus checks for gh authentication every time you run locus init. If authentication expires, re-run gh auth login.

---

Set Up an AI Provider CLI

Locus delegates code generation and analysis to an external AI CLI tool. You need at least one installed and authenticated.

Option A: Claude Code (Anthropic) -- default

Install Claude Code by following the official installation guide:

npm install -g @anthropic-ai/claude-code

After installation, launch claude once to complete the authentication flow. Claude Code manages its own API credentials -- no manual API key setup is required.

Option B: Codex (OpenAI)

Install Codex by following the official installation guide:

npm install -g @openai/codex

After installation, launch codex once to complete the authentication flow. Codex manages its own API credentials -- no manual API key setup is required.

Switching Providers

Locus defaults to Claude (claude-sonnet-4-6). You can change the provider and model at any time:

# Switch to Codex
locus config set ai.model codex-mini-latest

# Switch back to Claude
locus config set ai.model claude-sonnet-4-6

The provider is inferred automatically from the model name -- no need to set it separately.

---

Set Up Sandboxing (Recommended)

Locus can run AI agents inside Docker sandboxes for isolated, safe execution. This prevents agents from accessing host secrets, credentials, and system paths.

Why sandboxing matters: AI agents in full-auto mode have unrestricted access to your filesystem. Docker sandboxing ensures they only see what you allow via .sandboxignore rules, keeping .env files, API keys, and cloud credentials out of reach.

To set up sandboxing:

# 1. Verify Docker is available
docker sandbox ls

# 2. Create provider sandboxes
locus sandbox

# 3. Authenticate inside each sandbox
locus sandbox claude
locus sandbox codex

Full guide: Sandboxing Setup (Docker-First)

Without sandboxing, AI agents run with full access to your host filesystem. For teams and production use, sandboxing is strongly recommended.

---

Run Without Installing

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

npx @locusai/cli --version
npx @locusai/cli init
npx @locusai/cli plan "Build a REST API"

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

---

Next Steps

1. Sandboxing Setup -- set up Docker sandbox isolation

2. Quickstart -- complete one full issue-to-PR workflow