Headmaster by GCAP Labs

The Headmaster desktop app can run your agent in two places. Cloud Mode runs it on a Headmaster-hosted runtime that belongs to your account. Work Mode runs it on your own computer, next to your files and tools. You can switch between them at any time, and your memory follows you either way.

This page explains what each mode is, what it can and cannot do, how to set each one up, and how to pick the right one for a task.

The short version

	Cloud Mode	Work Mode
Where the agent runs	On a hosted runtime assigned to your account	On this computer
Keeps working when your computer is off	Yes	No
Can read and edit files on your computer	No	Yes, starting in the folder you choose
Can run commands on your computer	No	Yes, subject to your approval mode
Available in web chat	Yes	No
Setup	Sign in with an approved account	A one-time install of the local Work engine
Model sign-ins	Its own	Its own, separate from Cloud
Memory	One memory, shared with Work and web chat	One memory, shared with Cloud and web chat
File checkpoints and command allowlist	Not available	Available

If you only remember one thing: Cloud is for work that should live online and keep going. Work is for work that touches your computer.

Cloud Mode

What it is in Cloud Mode

In Cloud Mode your agent runs on a runtime that Headmaster hosts and assigns to your account. The desktop app is a window onto that runtime. So is web chat at headmaster.gcaplabs.com. Both show the same Cloud chats.

Cloud Mode is the default choice in setup, because there is nothing to install.

What you need

A Headmaster account. You can sign in with email and password, or with Continue with Google.
An account that has been approved for Cloud. Public sign-up is off during the beta, so new accounts wait for approval. Until then, the app shows This account is not approved to use Headmaster yet.

What Cloud Mode can do

Chat, research, write, and use its built-in tools, such as web browsing.
Use connections and MCP servers you add for Cloud. See Connections and MCP servers.
Run scheduled tasks while your computer is closed.
Remember things across chats, using the same memory as Work Mode and web chat. See Memory.

What Cloud Mode cannot do

It cannot see files, folders, or apps on your computer.
It cannot run commands in your terminal. Commands it runs happen on the hosted runtime, never on your PC.
Some pages in the desktop app only work in Work Mode. When you open one of them in Cloud, you see Not available in Cloud yet with a prompt to switch.
File checkpoints and the permanent command allowlist are Work Mode only, so they do not appear in Cloud settings.
Local speech engines that run on your own computer are not offered in Cloud. Cloud voice uses hosted providers.

Staying connected

If the connection to your Cloud runtime drops, Headmaster tries to reconnect on its own. You only see a message if it stays down. Your chats are kept on the runtime, so nothing is lost while you are offline.

Work Mode

What it is in Work Mode

In Work Mode the agent runs on your computer, using a local engine that Headmaster installs and manages for you. It can work with your real files and your terminal, so it is the right choice for coding, editing documents in a folder, organizing files, or anything else that needs your machine.

First-time setup

The first time you choose Work Mode, Headmaster shows Headmaster Work Mode needs a one-time setup. Choose Set up Work Mode and the app installs the Work engine for you. You see each step and its progress, for example "3 of 7 steps complete". Future launches reuse this setup.

If a step fails, the app shows Work Mode setup failed and stops at that step. You can:

Choose Show details to see what happened, or Copy output to share it with support.
Close any other Headmaster window, then choose Reload and retry.
Choose Use Cloud Mode instead and come back to Work later.

On a platform where the automatic install is not available yet, the app shows a single install command to copy and run in Terminal. After it finishes, choose I've run it -- retry.

The working folder

Work Mode starts each new chat in a folder on your computer. That is where the agent reads and writes files by default.

Set it in Settings → Sessions → Default project directory. Choose Choose or Change to pick a folder, or Clear to go back to the default.
If you leave it unset, new chats start in your home folder.
A change applies to new chats. Start a new chat (Ctrl+N, or Cmd+N on a Mac) to use it.

Tip: point the working folder at the project you care about, not your whole home folder. It keeps the agent focused and makes approvals easier to read.

Models in Work Mode

Work Mode keeps its own model sign-ins, separate from Cloud. If you signed in to ChatGPT for Cloud, sign in again for Work. New installs start with Headmaster Lite, which is free with daily limits during the beta. Connect your own provider any time to go past those limits. See Models and providers.

What Work Mode adds

File and terminal tools on your computer, controlled by your approval mode.
File checkpoints, so you can roll back edits the agent made. See Approvals and safety.
Command allowlist, so commands you trust stop asking for approval.
Custom endpoints and local models, so you can use a model server on your own machine or network.

Keeping the Work engine warm

When you switch to Cloud, the Work engine can keep running in the background. The setting Keep Work engine running while in Cloud (in Settings → Sessions) controls this.

On: switching back to Work is instant.
Off: the Work engine stops after 30 idle minutes in Cloud. The next switch to Work takes a little longer while it starts.

Switching modes

Use the mode switch in the desktop app sidebar. Pick Cloud or Work.

Cloud is unavailable until you sign in.
Work needs its one-time setup first.
Your memory is the same in both modes, so the agent still knows your preferences after a switch.
Chats belong to the mode they were started in. A Work chat stays on your computer. A Cloud chat stays on your Cloud runtime and also shows in web chat.

When a switch fails

If a switch does not complete, you see Couldn't switch to Cloud Mode or Couldn't switch to Work Mode with a reason and a Retry button. Common reasons:

Message	What it means	What to do
This account is not approved to use Headmaster yet.	Your account is waiting for Cloud approval.	Wait for approval, or use Work Mode meanwhile.
Sign in again to switch modes.	Your sign-in expired.	Sign in from Settings → Account.
No workspace is set up for this mode yet.	The mode has not been set up.	Run Work setup, or sign in for Cloud.
A mode change is already in progress.	You clicked twice.	Wait a moment.
Could not connect. Try again.	The network or runtime did not answer.	Check your connection, then Retry.
Could not confirm the switch. Try again.	The switch started but did not report back.	Choose Retry.

Settings and modes

Settings are grouped by where they apply. At the top of each settings page, a note tells you which one you are editing:

App: the desktop app itself, in both modes. Theme, layout, shortcuts.
Account: saved to your Headmaster account and used in both modes. Your own API keys live here.
Cloud Mode: only for Cloud chats.
Work Mode and This computer: only for Work Mode on this computer.

So if a setting seems to have no effect, check that you changed it for the mode you are using.

Which mode should I use?

Example: planning a trip

You want a day-by-day plan and a packing list, and you want to check it from your phone later. Use Cloud. It needs no files, and the chat is in web chat too.

Example: fixing a bug in your code

The project is on your laptop. Use Work, set the working folder to the project, and keep approvals on Manual while the agent runs tests and edits files.

Example: a daily news digest

You want a summary every morning, even if your laptop is shut. Use a Cloud scheduled task.

Example: tidying your Downloads folder

The files are on your computer. Use Work, set the working folder to Downloads, and turn on file checkpoints first so you can undo.

Tips

Start in Cloud for anything that does not need your files. It is always ready and keeps going without you.
Use Work for anything that touches your computer, and keep the working folder narrow.
Remember that model sign-ins are separate per mode. If a model is missing in one mode, sign in there too.

Troubleshooting

Cloud is greyed out. Sign in first. If you are signed in, your account may still be waiting for approval.
Work setup keeps failing. Close every other Headmaster window, then Reload and retry. If it still fails, use Copy output and contact support.
The agent cannot find my file in Cloud. Cloud cannot see your computer. Switch to Work, or attach the file to the chat.
The agent edits files in the wrong place. Check the default project directory, then start a new chat.

Cloud and Work modes