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

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.