CLI & Configuration

Running Clustr from the command line and configuring your workspace.

Quick start

npx clustr-ai

This is the simplest way to run Clustr. It downloads the package, auto-builds if needed, and starts the server on port 3100.

Environment variables

Mobile access

Clustr has built-in support for monitoring and controlling your agent swarm from a phone or tablet on the same network.

1. Click the Connect Phone button (📱) in the dashboard header.
2. A QR code will appear — scan it with your phone's camera.
3. Your phone opens the dashboard with a secure session token. No account or sign-in needed.

The dashboard is a PWA — you can add it to your home screen for a native-app feel.

Remote access over cellular

To reach your Clustr instance from outside your local network (e.g. over a cellular connection), start Clustr with the tunnel flag:

CLUSTR_TUNNEL=1 npx clustr-ai

This starts a Cloudflare tunnel and displays a public URL you can use from anywhere. The pairing QR code will automatically include the tunnel URL.

Data storage

Clustr stores all runtime data in a local folder on your machine (created automatically on first run). This includes the agent database, the shared rules file, temporary agent configs, and any uploaded images. Everything stays local — nothing is sent to external servers.

Prerequisites

• Node.js 18+ — required for the Clustr server
• Claude Code CLI — install with npm install -g @anthropic-ai/claude-code (for Claude agents)
• Codex CLI — install with npm install -g @openai/codex (for Codex agents)

You need at least one of the AI CLIs installed. You can use both in the same workspace.