Quick Start

This guide gets you from zero to a running Open Astra gateway in under 60 seconds using npx astra.

Step 1 — Run npx astra

npx astra

On the first run, the setup wizard launches automatically. It takes about 30 seconds to complete.

Step 2 — Complete the wizard

The wizard asks four questions:

1. Which LLM provider do you want to use? — Select one or more from the list (OpenAI, Anthropic, Groq, Gemini, Grok, Mistral, OpenRouter, Ollama, vLLM, Bedrock)
2. Enter your API key — Paste the key for your selected provider
3. What port should the gateway use? — Default is 3000; press Enter to accept
4. Generate JWT secret? — Press Enter to auto-generate a secure secret

After the wizard finishes, your config is saved to ~/.astra/config.json and the gateway starts automatically.

What happens on first run

After the wizard completes, Open Astra starts several services in sequence:

1. Pulls and starts astra-postgres and astra-typesense Docker containers
2. Waits for both services to be healthy (usually 5–10 seconds)
3. Runs all 140 database migrations automatically
4. Loads astra.yml if present, or uses built-in defaults
5. Registers 109 skills and 67 tools
6. Starts the Express gateway on the configured port

You will see output like:

[astra] Starting containers...
[astra] postgres   ✓ healthy
[astra] typesense  ✓ healthy
[astra] Running 140 migrations... done
[astra] Loaded 3 agents from astra.yml
[astra] Registered 109 skills, 67 tools
[astra] Gateway listening on http://localhost:3000

Step 3 — Verify the gateway works

Open a new terminal and send a test request:

# Health check
curl http://localhost:3000/health

# Expected response:
# { "status": "ok", "version": "...", "uptime": 12 }

Or use the interactive CLI to chat with an agent immediately:

npx astra chat

# You should see:
# Connected to http://localhost:3000
# Agent: default-agent (gpt-4o)
# Type a message and press Enter. /help for commands.
#
# > Hello! What can you do?

Next steps

• Configure astra.yml — define your agent team with custom models, skills, and spawn rules
• Create agents — add specialist agents for coding, research, or domain-specific tasks
• Connect a channel — connect Telegram, Slack, or Discord so your team can talk to agents from anywhere
• Explore memory — understand how the 5-tier memory system keeps agents smart across sessions