Foyer

Quickstart

The half-hour path — clone, configure a business, point Twilio and Google Calendar at it, send a test SMS, watch the agent reply. Assumes Postgres 16, PHP 8.3, Python 3.12, Node 22 already in place.

1. Clone and install

git clone https://github.com/philiprehberger/foyer.git
cd foyer
composer install
npm --prefix web install
npm --prefix widget install
python -m venv workers/agent/.venv
workers/agent/.venv/bin/pip install -r workers/agent/requirements.txt

The PHP half is the API plus Filament admin plus queue workers. The Next.js half is this docs site plus the live demo. The Python half is the agent worker — it never opens a Postgres connection, only talks to the loopback-bound internal API.

2. Postgres schema

Foyer needs Postgres 16 with the btree_gist extension — the slot-hold and bookings exclusion constraints are the load-bearing guard against double-booking.

createuser foyer --pwprompt
createdb foyer --owner=foyer
psql -d foyer -c "CREATE EXTENSION IF NOT EXISTS btree_gist;"
cp .env.example .env
# Edit .env: DB_*, REDIS_*, FOYER_INTERNAL_SECRET, TWILIO_*, GOOGLE_*
php artisan migrate

3. Create a business

A business is the tenant boundary — services, hours, area, quiet hours, the Twilio number, the Calendar. The seeder loads the Anchor Plumbing fixture under fixtures/anchor-plumbing/config.json.

php artisan db:seed --class=AnchorPlumbingSeeder
# Or create via the admin:
php artisan serve
# visit http://localhost:8000/admin and create a user

4. Wire Twilio and Calendar

The setup pages walk both of these end to end — Twilio for the inbound webhook and status callback, 10DLC for brand and campaign registration, and Google Calendar for the OAuth flow scoped to calendar.events.

5. Start the processes

Four things run in development:

# Terminal 1 — API + admin
php artisan serve

# Terminal 2 — Horizon (queues: agent, twilio-outbound, slot-cleanup, calendar-sync)
php artisan horizon

# Terminal 3 — FastAPI agent worker
workers/agent/.venv/bin/uvicorn workers.agent.main:app --port 9101

# Terminal 4 — Docs + demo (optional in dev)
npm --prefix web run dev

6. Text the number

With Twilio pointed at POST /v1/sms/inboundand ngrok or Cloudflare Tunnel exposing the local API, text the business’s Twilio number. The webhook fast-acks within 500ms, an AgentTurn job lands on Redis, the FastAPI worker picks it up, calls the LLM with the configured scope, and posts the result back through the loopback-bound HMAC-protected internal API. Within seconds you should get a reply.

What to read next