Skip to main content

​
Before you start

You need:
  • Node.js >=20
  • an OpenRouter API key
  • a local checkout of this repo

​
1. Install

npm install

​
2. Configure .env

Copy .env.example to .env and set: 
OPENROUTER_API_KEY=your_openrouter_key_here
ASTROLABE_API_KEY=set_a_long_random_secret_here
PORT=3000
Generate ASTROLABE_API_KEY with: 
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

​
3. Start Astrolabe

npm start
Astrolabe listens on http://localhost:3000.

​
4. Check health

curl http://localhost:3000/health \
  -H "Authorization: Bearer your_astrolabe_api_key"

​
5. Test the primary Responses endpoint

curl -X POST http://localhost:3000/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_astrolabe_api_key" \
  -d '{"model":"astrolabe/auto","input":"Write a one-line greeting.","stream":false}'

​
6. Inspect route metadata

Look for:
  • x-astrolabe-category
  • x-astrolabe-lane
  • x-astrolabe-initial-model
  • x-astrolabe-final-model
  • x-astrolabe-route-label
For JSON responses, also inspect the inline astrolabe metadata block.

​
7. Optional legacy compatibility test

curl -X POST http://localhost:3000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_astrolabe_api_key" \
  -d '{"model":"astrolabe/auto","messages":[{"role":"user","content":"Say hello in one line."}],"stream":false}'

​
8. Validate the static roster

npm run validate:models
This checks Astrolabe’s checked-in manifest against OpenRouter’s current catalog without changing runtime behavior.