Skip to main content

​
Prerequisites

Before installing Max, make sure you have the following:
  • Node.js v18 or later — nodejs.org
  • npm — included with Node.js
  • GitHub Copilot CLI — installed and authenticated
The installer checks for Node.js and the Copilot CLI automatically and will warn you if either is missing.

​
Install the Copilot CLI

If you don’t have the Copilot CLI installed yet: 
npm install -g @github/copilot
Then authenticate: 
copilot login
You must be authenticated before starting Max. The orchestrator session depends on a valid Copilot CLI login.

​
Install Max

There are two ways to install Max. The curl script is preferred — it checks your prerequisites and runs first-time setup automatically. 
curl -fsSL https://raw.githubusercontent.com/burkeholland/max/main/install.sh | bash

​
What the curl installer does

The install.sh script runs the following steps:
  1. Checks that Node.js v18+ is installed
  2. Checks that npm is installed
  3. Checks for the Copilot CLI (warns if missing, does not block)
  4. Checks for gogcli (optional — enables Gmail, Calendar, Drive)
  5. Runs npm install -g heymax to install the max command
  6. Launches max setup to walk you through first-time configuration
If you install via npm install -g heymax directly, run max setup manually afterwards to create your config.

​
First-time setup

The setup wizard creates ~/.max/ and walks you through configuration: 
max setup
Setup covers:
  • Telegram (optional) — provide your bot token and Telegram user ID to enable remote control from your phone
  • Google services (optional) — configure gogcli for Gmail, Calendar, and Drive access
  • Default model — choose from the models available on your Copilot subscription
All settings are saved to ~/.max/.env. You can re-run max setup at any time to change them.

​
Optional dependencies

Telegram lets you send messages to Max from your phone and receive notifications when background tasks finish.To set it up, you need:
  1. A Telegram bot token from @BotFather
  2. Your Telegram user ID (get it from @userinfobot)
Run max setup and answer yes when prompted for Telegram configuration.
Set your Telegram user ID during setup. Without it, anyone who finds your bot could send it commands.
The gogcli tool enables a bundled skill that gives Max access to Gmail, Google Calendar, and Google Drive.Install it with Homebrew:
brew install steipete/tap/gogcli
Then configure it through max setup → Google services, or follow the Google services guide.

​
Verify the installation

Confirm Max is installed correctly: 
max help
Or check the version: 
max --version
You should see output like: 
max v1.2.2 — AI orchestrator powered by Copilot SDK

Usage:
  max <command>

Commands:
  start       Start the Max daemon (Telegram bot + HTTP API)
  tui         Connect to the daemon via terminal UI
  setup       Interactive first-run configuration
  update      Check for updates and install the latest version
  help        Show this help message

Quickstart

Start the daemon and send your first message.

Configuration

Learn about all available configuration options.

Build docs developers (and LLMs) love

Get started for freeTalk to us