Beginner Guide

A complete walkthrough from zero to a running Edward — no experience required.

What You Will Need

  • A Mac — Edward relies on macOS for iMessage, Apple Calendar, and other integrations. Windows and Linux are not supported.
  • An internet connection — to download software and talk to the Claude AI API.
  • About 20 minutes — most of that is waiting for things to install.
  • An Anthropic API key — this is how Edward connects to Claude. We'll walk you through getting one in Step 6. It costs a few cents per conversation (typically under $0.10/day for casual use).

Step 1: Open Terminal

Terminal is a built-in app on your Mac that lets you type commands. You don't need to know how it works in detail — just type (or paste) exactly what this guide shows you.

To open it:

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

A window with a blinking cursor will appear. This is where you'll paste commands for the rest of this guide.

Step 2: Install Homebrew

Homebrew is a package manager for macOS — it makes installing developer tools easy. Paste this command into Terminal and press Enter:

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

It will ask for your Mac password (the one you use to log in). When you type it, nothing will appear on screen — that's normal. Just type it and press Enter.

This can take 5–10 minutes. When it finishes, it may show instructions to add Homebrew to your PATH. If so, copy and paste those commands too.

Verify it worked:

brew --version

You should see something like Homebrew 4.x.x.

Step 3: Install Git, Node.js, and Python

Edward needs these three tools. Install them all at once:

brew install git node [email protected]

This takes a few minutes. When it finishes, verify each one:

git --version      # Should show git version 2.x+
node --version     # Should show v18+ or v20+
python3 --version  # Should show Python 3.11+

Step 4: Get the Edward Code

"Cloning" a repository means downloading a copy of the code to your computer. Run these commands to clone Edward to your Desktop:

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

You should now have a meet-edward folder on your Desktop.

Step 5: Run the Setup Script

Edward comes with a setup script that installs everything it needs — PostgreSQL (the database), Python packages, and frontend dependencies.

./setup.sh

This will take a few minutes. You'll see a lot of output scrolling by — that's normal. Wait until you see a message indicating setup is complete.

If you see "Permission denied":

chmod +x setup.sh
./setup.sh

Step 6: Get an Anthropic API Key

Edward uses Claude (made by Anthropic) as his brain. You need an API key to connect them.

  1. Go to console.anthropic.com
  2. Create an account or sign in
  3. Go to API Keys in the left sidebar
  4. Click Create Key
  5. Copy the key — it starts with sk-ant-

You'll need to add a payment method. Typical personal usage costs a few cents per conversation — well under $5/month for most people.

Step 7: Add Your API Key

Edward stores its settings in a file called .env (short for "environment"). Open it in TextEdit:

open -e backend/.env

Find the line that says ANTHROPIC_API_KEY= and paste your key after the equals sign:

ANTHROPIC_API_KEY=sk-ant-your-key-here

Save the file (Cmd + S) and close TextEdit.

Step 8: Start Edward

Back in Terminal, make sure you're in the meet-edward folder, then run:

./restart.sh

You should see output indicating both the backend and frontend are starting. Wait about 10 seconds for everything to initialize.

Step 9: Open in Browser

Open your web browser (Safari, Chrome, etc.) and go to:

http://localhost:3000

localhost means "this computer" — Edward is running right here on your Mac, not on someone else's server.

  1. You'll be asked to set a password — this protects your Edward instance
  2. After logging in, type a message like "Hi, who are you?"
  3. Edward should respond. If he does, you're all set!

Why Does My Mac Need to Stay On?

Edward runs on your Mac. When your Mac sleeps or shuts down, Edward stops too. This is normal — he'll pick up right where he left off when you restart.

To start Edward again after a reboot:

cd ~/Desktop/meet-edward
./restart.sh

Accessing Edward from Your Phone

If your phone is on the same Wi-Fi network as your Mac, you can access Edward from your phone's browser.

First, find your Mac's local IP address:

ipconfig getifaddr en0

This will print something like 192.168.1.42. On your phone, open a browser and go to:

http://192.168.1.42:3000

(Use the actual number your Mac showed, not the example above.)

Save as Home Screen App (PWA)

Edward works as a Progressive Web App — you can save it to your phone's home screen for an app-like experience.

iPhone (Safari)

  1. Open Edward in Safari
  2. Tap the Share button (square with arrow)
  3. Scroll down and tap Add to Home Screen

Android (Chrome)

  1. Open Edward in Chrome
  2. Tap the three-dot menu (top right)
  3. Tap Add to Home screen

Accessing Edward from Anywhere

By default, Edward is only accessible on your local network. To access him from anywhere (outside your home), you can use a tunnel service.

Cloudflare Tunnel (recommended, free)

brew install cloudflared
cloudflared tunnel --url http://localhost:3000

This gives you a public URL like https://random-name.trycloudflare.com that works from anywhere. The tunnel runs as long as your Terminal window is open.

ngrok (alternative)

brew install ngrok
ngrok http 3000

Common Issues

"brew: command not found"

Homebrew wasn't added to your PATH. Close Terminal, open a new one, and try again. If it still doesn't work, re-run the Homebrew install command from Step 2.

"Permission denied"

The script needs to be marked as executable:

chmod +x setup.sh restart.sh
./setup.sh

Port already in use

Something else is using port 3000 or 8000. Find and stop it:

lsof -i :3000
lsof -i :8000

The output will show a PID number. Stop the process with kill <PID>.

API key errors

Double-check that your backend/.env file has the correct key with no extra spaces or quotes. The line should look exactly like:

ANTHROPIC_API_KEY=sk-ant-your-actual-key

PostgreSQL not running

If Edward can't connect to the database:

brew services list          # Check if postgresql is running
brew services start postgresql@16  # Start it

Checking logs

If something isn't working, check the logs for error messages:

cat /tmp/edward-backend.log
cat /tmp/edward-frontend.log

Once Edward is running, head to the Configuration guide to customize your setup.