Installation and Setup

System requirements

Platform	Requirement
macOS	Apple Silicon or Intel, 16GB RAM recommended
Windows	Windows 10 or later
Disk	2GB free space

Step 1: Install the client

Download the installer for your platform from the official site, then drag it into Applications (Mac) or run the installer (Windows).

First launch asks you to sign in.

Step 2: Configure a model

WorkBuddy is the workbench; a model powers it. Two routes:

Route A: use the built-in model Works out of the box.

Route B: connect your own model or a third party Useful combinations:

General work: a strong commercial model
Local inference: MLX or Ollama on Mac (note: some custom architectures need a specially built runtime)
Behind a proxy: configure your local proxy address and port in settings

Step 3: Authorize a workspace

This is the step people get wrong.

mkdir -p ~/WorkBuddy

Create one dedicated directory, put projects inside, and authorize only that directory.

Don’t authorize ~/Desktop or ~/Downloads wholesale — a mistake there has a much larger blast radius.

Mac-specific gotchas

1. npm/node commands get blocked

In sandboxed environments, npm install or npm run build may fail with CODEBUDDY_BROKER_DENY. The NODE_OPTIONS environment variable has a shim script injected into it. Clear it per command:

env -u NODE_OPTIONS npm install
env -u NODE_OPTIONS npm run build

2. Permission prompts

The first write triggers a system prompt. Choose “Always Allow” to avoid repeating it.

3. Fanless models

MacBook Air models without a fan will throttle under sustained local model load. Plug in for long runs.

Verify the install

Run the smallest possible end-to-end test:

Write a Python script that counts the total number of words across all .md files in this directory, then run it.

If it creates the script, executes it, and shows output, the whole chain works: model → tools → file operations.

Choosing a Work Mode.