Health Check

After starting Open Astra, use the health endpoint and the astra doctor command to verify every service is running correctly before deploying or directing traffic to the gateway.

Health endpoint

The gateway exposes an unauthenticated health endpoint at GET /health. It returns HTTP 200 when all three services (PostgreSQL, Typesense, and the scheduler) are reachable, or HTTP 503 with a failing service name if any are down.

bash

# Unauthenticated health probe
curl http://localhost:3000/health

# Response when all services are healthy:
{
  "status": "ok",
  "version": "0.9.4",
  "uptime": 3821,
  "services": {
    "postgres":   "ok",
    "typesense":  "ok",
    "scheduler":  "ok"
  }
}

npx astra doctor

npx astra doctor performs a deeper check — it validates every required environment variable, tests database connectivity, verifies that all 16 migrations have been applied, checks that pgvector is installed, and reports which channels are configured vs. disabled.

bash

npx astra doctor

# Example output:
[✓] Gateway         reachable at http://localhost:3000
[✓] PostgreSQL      connected — 16 migrations applied
[✓] Typesense       connected — 3 collections healthy
[✓] pgvector        extension installed (version 0.7.0)
[✓] JWT_SECRET      set (64 chars)
[✓] LLM providers   1 configured (openai)
[✗] SMTP            not configured (email channel disabled)
[✗] TELEGRAM_TOKEN  not configured (Telegram channel disabled)

Lines marked [✗] are non-fatal warnings. Missing channel tokens disable that channel but do not affect the gateway or other channels.

Agent ping

After the gateway starts, send a test message to verify the full agent loop is working — inference, memory, and tool registration:

bash

# Send a test message to the default agent
curl -X POST http://localhost:3000/chat \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "message": "ping", "agentId": "default-agent" }'

# Expected:
{ "role": "assistant", "content": "pong" }

Service status reference

Service	What doctor checks	Common fix
PostgreSQL	TCP connection + migration count	Run `docker compose up -d postgres` or check `DATABASE_URL`
Typesense	API key + collection health	Run `docker compose up -d typesense` or check `TYPESENSE_API_KEY`
pgvector	`CREATE EXTENSION IF NOT EXISTS vector`	Use the `pgvector/pgvector` Docker image, not plain `postgres`
JWT_SECRET	Presence + minimum 32 chars	Add `JWT_SECRET=$(openssl rand -hex 32)` to `.env`
Scheduler	11 cron jobs registered	Gateway restarted; cron jobs are in-process (no separate service needed)

ℹUse GET /health as your load balancer health probe. It is fast (<5ms), requires no authentication, and returns 503 on any service failure so traffic is automatically withheld.

See also: Install Overview for system requirements, Upgrading for how to apply new versions safely.