Local Development

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 dev

Step 2: Start example backend

# Recommended — ShopCo pipeline demo (YAML manifest + multi-stage onboarding)
export AELIO_SDK_SECRET=change-me-in-production
pnpm --filter aelio-sample-saas start

# Or minimal Express example (tools only, no pipeline)
pnpm --filter aelio-example-express start

Step 3: Open demo

URL	What
http://localhost:3010/demo.html	ShopCo pipeline demo — click New user for fresh onboarding
http://localhost:3010/ready	Server readiness + pipeline registration status
http://localhost:3010/health	Server health check
http://localhost:8081/health	ShopCo sample backend health

One-liner (server + ShopCo demo)

pnpm start   # boots Aelio server + ShopCo sample backend together

See Pipeline YAML Manifest and ShopCo Sample SaaS for how the YAML onboarding flow works.

Test a conversation

Open the demo, click Chat, and ask:

What is my order status?

Expected flow: Widget → Aelio Server → LLM → SDK getOrderStatus → reply.

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:all

Common 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`