npx astra (zero-config)

The npx astra command is the fastest way to run Open Astra. It requires no prior installation, manages Docker services automatically, and persists your configuration between runs.

First-run wizard

On your first run, Open Astra detects that no configuration exists and launches an interactive setup wizard in your terminal.

npx astra

The wizard starts with a QuickStart vs Advanced prompt:

• QuickStart (Y, default) — asks only for your provider and API key; everything else (ports, extra providers, Brave Search, team workspace) is defaulted. Takes about 10 seconds.
• Advanced (n) — full wizard: additional provider keys, Brave Search API key, custom ports, and optional team workspace creation.

QuickStart steps

1. Provider selection — choose your default LLM provider: Claude (Anthropic), OpenAI, Grok (x.ai), Gemini (Google), or Ollama (local, no API key)
2. API key entry — paste the API key for the selected provider (masked input). Skipped automatically for Ollama.
3. Health check — optionally starts Docker services and waits for PostgreSQL and Typesense to report healthy before exiting.

Additional steps in Advanced mode

3. Additional provider keys — add API keys for other providers (used for fallback or multi-model routing)
4. Brave Search — optional; enables the url-fetch web search tool
5. Ports — customize gateway (default 8080), PostgreSQL (default 5433), or Typesense (default 8108) ports if they conflict
6. Team workspace — optionally create a named shared workspace

After the wizard completes, configuration is written to ~/.astra/config.json. If no astra.yml is found in the current directory or at ~/.astra/astra.yml, a default agent config is also generated at ~/.astra/astra.yml. On subsequent runs, the wizard is skipped and the saved config is used directly.

Automatic Docker management

Open Astra requires PostgreSQL and Typesense as backing services. The npx astra command handles this automatically:

• Checks if Docker is running; exits with a clear error if not
• Pulls postgres:17-alpine and typesense/typesense:27.1 if not already present
• Starts containers named astra-postgres and astra-typesense with persistent named volumes
• Waits for both services to report healthy before starting the gateway
• On subsequent runs, skips pulling if images are already present

# Containers created automatically:
# astra-postgres   → localhost:5432  (volume: astra-pg-data)
# astra-typesense  → localhost:8108  (volume: astra-ts-data)
#
# Gateway listens on port 8080 by default

Config persistence

All configuration written by the wizard is stored at ~/.astra/config.json. This file is loaded into the process on each run.

{
  "defaultProvider": "claude",
  "apiKeys": {
    "ANTHROPIC_API_KEY": "sk-ant-..."
  },
  "jwtSecret": "...",
  "internalApiKey": "...",
  "typesenseApiKey": "...",
  "pgPassword": "...",
  "gatewayPort": 8080,
  "pgPort": 5433,
  "typesensePort": 8108
}

CLI flags

Non-interactive / CI installs

Pass --non-interactive (or --yes / -y) to skip all prompts. Config is derived entirely from environment variables:

# CI / scripted install — no prompts
DEFAULT_PROVIDER=claude \
  ANTHROPIC_API_KEY=sk-ant-... \
  npx astra --non-interactive

# Alias forms
npx astra --yes
npx astra -y

Reconfiguring

# Reconfigure at any time
npx astra setup

# Reset (wipe existing config) then re-run wizard
npx astra --reset

# Skip the QuickStart prompt and go straight to fast path
npx astra --quickstart
npx astra -q

CLI subcommands

The astra binary exposes several subcommands:

npx astra chat

Opens an interactive REPL that connects to a running Astra gateway and lets you chat with any configured agent.

npx astra chat
# Connects to http://localhost:8080 by default
# Type a message and press Enter
# Use /agent <id> to switch agents
# Use /help to see all slash commands

npx astra stop

Gracefully stops and removes the Docker containers started by npx astra. Data volumes are preserved so your memory and sessions survive across restarts.

npx astra stop
# Stops: astra-postgres, astra-typesense
# Preserves: astra-pg-data, astra-ts-data volumes

npx astra doctor

Runs a suite of 12 diagnostic checks and reports status across 6 categories: connectivity, config, migrations, agents, providers, and memory. See CLI Reference for full output format.

npx astra costs

Displays a terminal-based cost dashboard showing token usage and estimated spend per agent, per provider, and per day. Pulls data from the Postgres billing tables populated by the agent loop.