Beginner guide

From a Mac to a running Edward, one step at a time. No experience needed.

What you will need

  • A Mac with Apple silicon (an M1 or later) that can stay on and stay logged in. Edward runs on this Mac, so when it sleeps, he does too. A Mac mini makes a good always-on host. Intel Macs are not supported.
  • An Anthropic API key, which is how Edward talks to Claude. You pay Anthropic for what he uses, and Edward stops himself at a daily cap ($5 by default; you can change it).
  • About 30 minutes, most of it waiting for things to download and install.

Step 1: Open Terminal

Terminal is the Mac app for typing commands. You don’t need to know how it works: paste exactly what this guide shows and press Return.

  1. Press Cmd + Space to open Spotlight
  2. Type Terminal and press Return

Step 2: Install Apple’s command-line tools

xcode-select --install

A window asks to install the tools. Click Install and wait for it to finish. If Terminal says they are already installed, move on.

Step 3: Install Homebrew

Homebrew installs the software Edward is built on (Python, PostgreSQL and Node). Paste this and press Return:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

It asks for your Mac password. Nothing appears while you type it; that is normal. When it finishes, it prints Next steps with two or three commands that add Homebrew to your path: paste those too. Then check:

brew --version

Step 4: Get an Anthropic API key

  1. Go to console.anthropic.com and sign in or create an account
  2. Add a payment method or credits under Billing
  3. Open API Keys and click Create Key
  4. Copy the key (it starts with sk-ant-). The setup script asks for it in the next steps. Treat it like a password: don’t paste it into a chat or an email.

Step 5: Get the Edward code

cd ~
git clone https://github.com/ben4mn/meet-edward.git
cd meet-edward

This puts Edward in a meet-edward folder in your home folder. Keep it there rather than on the Desktop or in Documents, which macOS guards from background programs like Edward’s services.

Step 6: Run the setup script

./setup.sh

It asks three things:

  • Your name, which Edward calls you by
  • Your Anthropic API key from step 4
  • Your time zone, which reminders, quiet hours and “today” follow

Then it installs Python 3.12, PostgreSQL 16 and Node, builds the memory search extension, creates Edward’s database, downloads his Python and web packages and his headless browser, and builds two small helpers. It takes a while, and a lot of text scrolls past. It is safe to run again if anything stops it.

At the end it prints the path of a python3.12. Copy it somewhere: you need it if you want Edward to read your messages or calendar (step 10).

Step 7: Start Edward

bash scripts/install-launchagents.sh

This keeps Edward running: macOS starts him now and every time you log in, and restarts him if he stops. It also sets up a health check every five minutes and a nightly backup to ~/edward-backups.

The first start takes a few minutes: the backend downloads its small memory model and the app builds itself. To watch it, run tail -f /tmp/edward-backend.log (press Ctrl + C to stop watching).

Step 8: Choose your password

On the Mac that runs Edward, open your browser and go to http://localhost:3000. The first visit asks for a password and a one-time setup code. Get the code in Terminal:

cat backend/.setup_code

Type it in (capitals and dashes don’t matter) and choose your password. The code is deleted once the password is set. It exists so nobody else on your network can claim your Edward first, which is also why the first password can only be set on this Mac.

Step 9: Turn on what he may use

On a fresh install Edward can use none of his skills until you turn them on. Open the Edward tab, then:

  1. Mind → Skills: turn on what you want him to have. Shell/Bash is his own computer (a shell and a file editor), Web Search lets him search and read pages, iMessage lets him read and send messages, Push Notifications lets him reach your phone, and iOS Widget lets him fill the iPhone widget.
  2. House → Locale: check the time zone.

Then go to Chat and say hello. If he answers, Edward is running.

Step 10 (optional): Let him read your Mac’s apps

Edward reads Messages, Mail, Calendar, Reminders and Contacts from their own databases, which macOS protects. Grant access only for what you will use:

  • Full Disk Access: System Settings → Privacy & Security → Full Disk Access → +, press Cmd + Shift + G, paste the python path from step 6, and turn it on.
  • Calendars and Reminders (so he can add and change events when you ask): sitting at the Mac, run bash backend/scripts/eventkit_request_access.sh and click Allow.
  • Automation: macOS asks the first time Edward sends a message. Answer it at the Mac.

Reading your messages is still off until you turn on Attention → Listening → Configuration → Messages in the Edward tab. Read Listening & pings first: with it on, anyone can write @Edward in a chat with you and he answers from your own iMessage account.

Keeping the Mac awake

Edward runs as your user, so the Mac must be on and you must be logged in. In System Settings → Energy, turn on “Prevent automatic sleeping when the display is off” (on a laptop, keep it plugged in). After a restart, log in and Edward starts by himself.

Using Edward from your phone

Installing the app on your phone, push notifications and the microphone all need an https:// address. The usual way is a tunnel to port 3000 on your Mac:

  • Tailscale keeps Edward private to your own devices.
  • Cloudflare Tunnel gives him a public address. To try it: brew install cloudflared, then cloudflared tunnel --url http://localhost:3000, which prints a temporary https://…trycloudflare.com address. For a lasting one, set up a named tunnel and run it as a LaunchAgent.

Then tell Edward where he lives: add EDWARD_PUBLIC_BASE_URL=https://your-address to the .env file in the meet-edward folder (links in his pushes use it), and the tunnel’s LaunchAgent label as EDWARD_TUNNEL_LABEL so the health check watches it. Run ./restart.sh to apply.

Open the address on your phone and sign in. On iPhone, tap Share → Add to Home Screen; on Android, the ⋮ menu → Add to Home screen.

Common problems

“brew: command not found”

The Homebrew installer’s “Next steps” weren’t run. Close Terminal, open a new window and try again; if it still fails, run the commands Homebrew printed at the end of step 3.

Setup stops with an Intel or Rosetta message

Edward needs Apple silicon. If your Mac is Apple silicon, your Terminal is running under Rosetta: quit it, then in Finder → Applications → Utilities, select Terminal, press Cmd + I and untick “Open using Rosetta”.

The page says “still starting”, or won’t load

The first start can take several minutes. Watch tail -f /tmp/edward-backend.log and tail -f /tmp/edward-frontend.log, then try again. ./restart.sh restarts both.

I signed in but keep landing back on the login page

You are probably on a plain http:// address other than localhost. Use the Mac itself, or an https:// tunnel (above). On a home network you trust, EDWARD_COOKIE_SECURE=off in .env also works.

He says he can’t read my messages or calendar

Full Disk Access is missing, or went to a different python. The path changes when Homebrew upgrades Python, so grant the new one (setup and the LaunchAgent installer both print it) and run bash scripts/install-launchagents.sh again.

Is everything working?

Open http://localhost:3000/api/health/report while signed in: it lists what works and what doesn’t.

Next: Configuration lists the settings, and what ships switched off. The repository’s README has the same steps in brief.