Skip to main content

​
Getting Started

Setup time: about 5 minutes from download to your first conversation.

​
System requirements

​
Download and install

Homebrew (recommended)
Direct download
1

Download the .dmg

Download the .dmg file from the Headmaster site.
2

Open and install

Open the .dmg, drag Headmaster to your Applications folder.
3

First launch

On first launch, macOS may warn about an unidentified developer. Right-click → Open to bypass Gatekeeper.

​
First launch

On first launch, Headmaster:
1

Starts the local runtime

The background service that runs your agents initializes. You’ll see a splash screen for a few seconds.
2

Opens the main window

You’ll see a sidebar with your conversations and a chat composer at the bottom.
3

One-time setup

Pick a default model and optionally sign in to a model provider. You can skip this and do it later.
If you already have a CLI agent installed (Claude Code, Codex, Gemini CLI, etc.), Headmaster auto-detects it and shows it on the welcome screen. No extra setup needed.

​
Connect a model provider

The built-in agent needs at least one model provider before it can chat. Add an API key:
1

Open Settings

Click Settings in the left sidebar.
2

Go to Connections

Open Headmaster’s Library → Connections.
3

Add a provider

Click Add provider and pick one — supported: Gemini, OpenAI, Anthropic, DeepSeek, OpenRouter, and 25+ more.
4

Paste your API key

Paste your API key and click Save.
Multi-key rotation: Paste multiple API keys (comma-separated or one per line). Headmaster auto-rotates and skips invalid or rate-limited keys. See Models & providers.
The Connections area is PIN-protected. The default PIN is set on first run. Change it anytime in Headmaster’s Library → Advanced → Change PIN.

​
Send your first message

1

Create a new conversation

Click New chat in the left sidebar.
2

Pick an agent

Choose the built-in engine (default) or any detected CLI agent shown on the welcome screen.
3

Pick a model

Use the selector at the bottom-left of the input box. Each agent has its own model list.
4

Pick a specialist (optional)

A pre-configured persona with a specific role. See Specialists.
5

Type your message and send

Press Enter. The agent streams its response into the chat.

​
Example prompts to try

Tool calls (web searches, file reads, code execution) appear as expandable blocks in the response.

​
Explore the built-in features

​
File upload

  • Drag and drop files directly into the input box.
  • Pick from disk: click the + button to choose files or folders.
  • Supported: text files, images, code, PDFs, Office documents.

​
Multiple conversations

  • New conversation: click New chat — each conversation has independent memory.
  • Switch: pick any conversation in the left sidebar.
  • Search: type in the search bar to filter by title or content.

​
Project (working folder)

Open a project folder to give the agent scoped file access:
  1. Click the + button → Open folder.
  2. Pick a folder. The Workspace panel appears on the right with the folder tree.
  3. The agent can read and write files inside the folder without per-file approval.
A folder is locked per conversation. To work in a different folder, start a new chat — this prevents the agent from mixing up two projects’ file trees.

​
Approvals

When the agent wants to run a tool or access a file, it asks for your approval. Click Approve or Deny. See Approvals & human-in-the-loop.

​
First launch FAQ

Open Settings → Headmaster’s Library → Connections and add at least one provider’s API key. If a CLI agent is installed, it’s auto-detected on the welcome page — you can use it without adding a key.
Check:
  • Image generation is enabled in Settings → Advanced → Tools.
  • A model supporting image generation is selected.
  • See Image generation for the full configuration guide.
Use the model selector at the bottom-left of the input box. Each agent (built-in, Claude Code, Codex, etc.) exposes its own model list — switching the agent also switches the model list.
All stored locally:
  • macOS: ~/Library/Application Support/Headmaster/
  • Windows: %APPDATA%\Headmaster\
  • Linux: ~/.config/Headmaster/
Check <data folder>/logs/<today>.log for the startup error. Most common causes: a port conflict or a missing system dependency on Linux. See Troubleshooting.

​
Next steps

Models & Providers

Connect to 28+ LLM platforms and configure multi-key rotation.

Specialists

Explore the 20+ built-in personas or create your own.

The Schedule

Set up recurring automated tasks with cron scheduling.

Channels

Connect Telegram, WhatsApp, iMessage, and more.

Your Crew

Connect external CLI agents (Claude Code, Codex, Gemini CLI, etc.).

Troubleshooting

Common issues and how to fix them.