Getting Started

From zero to a running Edward instance in about five minutes.

Prerequisites

  • macOS — required for iMessage, Apple Services, and the scheduler
  • Homebrew — used by the setup script to install PostgreSQL
  • Node.js 18+ — for the Next.js frontend
  • Python 3.11+ — for the FastAPI backend
  • Anthropic API key — get one at console.anthropic.com

Quick Start

# Clone the repository
git clone https://github.com/ben4mn/meet-edward.git
cd meet-edward

# Run the setup script
./setup.sh

# Add your Anthropic API key to backend/.env
# ANTHROPIC_API_KEY=sk-ant-...

# Start both services
./restart.sh

That's it. Visit http://localhost:3000 and you're live.

What setup.sh Does

The setup script handles the full first-time installation:

  1. Installs PostgreSQL 16 and the pgvector extension via Homebrew
  2. Creates the edward database and user (default: edward/edward/edward)
  3. Creates a Python virtual environment in backend/venv/ and installs dependencies
  4. Installs frontend npm packages
  5. Generates a backend/.env template with required variables

What restart.sh Does

The restart script manages both services with graceful stop/start:

./restart.sh              # Restart both frontend + backend
./restart.sh frontend     # Restart only frontend
./restart.sh backend      # Stop and restart only backend

Logs are written to backend/logs/ and the frontend console. The backend also supports ./start.sh for direct startup (auto-activates the venv and installs any new dependencies).

Setting Your Password

The first time you visit localhost:3000, you'll be prompted to set a password. This is stored as a bcrypt hash in the database — Edward uses single-user JWT auth with HttpOnly cookies.

After setup, you can change your password anytime from the Settings page.

Verifying It Works

  1. Open http://localhost:3000 in your browser
  2. Set your password on first visit
  3. Send a message — Edward should respond with full context
  4. Check the debug panel (bottom of chat) for health status
Edward chat welcome screen after successful setup
If everything is working, you should see Edward's welcome screen.

Common Issues

PostgreSQL not running

brew services start postgresql@16

Missing API key

Make sure ANTHROPIC_API_KEY is set in backend/.env. Edward won't start the LangGraph agent without it.

Port conflicts

The backend runs on :8000 and the frontend on :3000. If either port is in use, check for existing processes:

lsof -i :8000
lsof -i :3000

Python version mismatch

Edward requires Python 3.11+. Check with python3 --version. If you have multiple Python versions, the setup script uses whichever python3 resolves to in your PATH.

Next up: configure your environment variables in the Configuration guide.