Installation
Local Development
Run the full Aelio stack locally for development and testing.
Full local stack
You need three processes running:
Terminal 1: Aelio Server (port 3010)
Terminal 2: Your backend (port 8080 or your choice)
Terminal 3: Your frontend (port 3000 or your choice)Step 1: Start Aelio Server
cd aelio # cloned monorepo
export AELIO_SDK_SECRET=change-me-in-production
export OPENAI_API_KEY=sk-... # optional, uses mock LLM without it
pnpm --filter @aelio/server devStep 2: Start example backend
# Minimal Express example
export AELIO_SDK_SECRET=change-me-in-production
pnpm --filter aelio-example-express start
# Or the Shopping Testbed demo
cd Aelio-Test
docker-compose up -d db
AELIO_SECRET=change-me-in-production AELIO_SERVER_URL=ws://127.0.0.1:3010 npm startStep 3: Open demo
| URL | What |
|---|---|
| http://localhost:3010/demo.html | Built-in demo page with widget |
| http://localhost:3010/health | Server health check |
| http://127.0.0.1:4173 | Shopping Testbed storefront |
| http://127.0.0.1:4173/chat | Shopping Testbed chat page |
One-liner (server + example)
pnpm start # boots server + example backend togetherTest a conversation
Open the demo, click Chat, and ask:
What is my order status?
Expected flow: Widget → Aelio Server → LLM → SDK getOrderStatus → reply.
Test without widget (SDK ingest)
curl -sS http://127.0.0.1:4173/api/aelio/ingest \
-H 'content-type: application/json' \
-d '{"channel":"web","from":"user@example.com","text":"Show me my cart"}'Run automated tests
AELIO_TEST_MODE=1 pnpm test:allCommon local dev issues
| Issue | Fix |
|---|---|
| Widget "Origin not allowed" | Add http://127.0.0.1:PORT to allowed_origins |
| SDK not connecting | Check AELIO_SDK_SECRET matches on both sides |
| Mock LLM responses | Set OPENAI_API_KEY for real responses |
| Widget bundle 404 | Build widget: pnpm --filter @aelio/chat build |