Quick Start

Get up and running in 5 minutes

Quick Start Guide

Get Prompt Stack up and running in under 5 minutes. This guide will walk you through the fastest path to a working development environment.

🎥 Setup Video

Watch the Setup Walkthrough

Learn how to get Prompt Stack running in under 5 minutes

Watch Video

📺 Video Contents: Installation walkthrough • Environment setup • Docker configuration • First run • Common gotchas • API key setup

Prerequisites

macOS, Linux, or Windows with WSL2
Docker Desktop installed and running
Node.js 18+ (for local development)
Git

1. Clone and Setup

Start by cloning the repository and running the automated setup:

# Clone the repository
git clone https://github.com/your-username/prompt-stack.git
cd prompt-stack

# Run the interactive setup
./setup.sh

🎯 Pro Tip: The setup script automatically detects your environment and guides you through configuration. No manual .env file editing required!

2. Start Development

Once setup completes, start the development environment:

# Start all services
make dev

# Or start services individually
make dev-frontend  # Frontend only
make dev-backend   # Backend only

3. Access Your App

Your application is now running:

Frontend: http://localhost:3000
Backend API: http://localhost:8000
API Docs: http://localhost:8000/docs

4. Demo Mode

By default, Prompt Stack runs in demo mode. This means you can explore all features without any API keys:

✅ Mock authentication (any email/password works)
✅ Demo AI responses
✅ Test payment flows
✅ In-memory vector search

5. Add Real Services

When you're ready to connect real services, use the setup script:

# Add authentication
./setup.sh supabase

# Add AI providers
./setup.sh ai

# Configure everything at once
./setup.sh configure

⚠️ Important: After adding API keys, you must log out and back in to refresh your authentication tokens!

Troubleshooting

Quick Diagnostics

If something isn't working, run the diagnostic tool:

# Full system diagnosis
./scripts/diagnose.sh

# Quick health check
./scripts/diagnose.sh --quick

Common Issues

Port already in use

# Find what's using port 3000
lsof -i :3000

# Kill the process
kill -9 [PID]

Docker containers won't start

# Reset containers
docker-compose down
docker-compose up -d

Environment variables not working

Docker requires a full restart for environment changes:

docker-compose down && docker-compose up -d

Developer Guide