Piper Morgan Alpha - Quick Start

Version: 0.8.6 Branch: production (stable alpha releases) For: Experienced developers who want to dive in fast

📍 Branch Info: This quickstart uses the production branch, which receives stable alpha releases. The main branch is for active development and may have bugs.

⚠️ If you hit issues, see ALPHA_TESTING_GUIDE.md for comprehensive troubleshooting.

Time & Storage Requirements

Step First Run Subsequent Runs
Clone repository 1-2 min (~91MB with –depth 1) N/A
Install Python packages 5-10 min (~216 packages, ~1GB) 1-2 min
Docker image download 10-30 min (~4GB, depends on connection) Skipped if cached
Database migrations 1-2 min 30 sec
Setup wizard 2-5 min N/A
Total (first time) 20-50 minutes 5-10 min

Storage Requirements:

What’s New in 0.8.6

M0 Conversational Glue - Piper now converses naturally. Workflows emerge from conversation; commands are shortcuts, not requirements.

Conversational Lens Tracking - Follow-up queries resolve correctly based on context (“what about next week?”).

Multi-Intent Handling - Compound queries handled coherently (“check my calendar and create an issue”).

Soft Workflow Invocation - Piper offers workflows naturally (“Sounds like you might want to set up a meeting…”).

Repository Management - Link GitHub repos to projects during setup or in Settings.

Bug Fixes - 7 post-launch issues resolved (error messages, auth, workflow polling).

Database Migration Required: Run alembic upgrade head after updating.

See Release Notes v0.8.6 for full details.

Choose Your Path

I want to… Use this guide Time
Try Piper Morgan (alpha testing) This guide (ALPHA_QUICKSTART.md) 20-50 min
Develop/contribute code SETUP.md 30-60 min

🔮 Future: A hosted version and Docker Hub images are planned for 2026, which will enable a true “5-minute setup” for users who just want to run Piper. For now, all paths require the developer setup.

Prerequisites

For macOS/Linux/WSL2:

# Fast clone (~91MB instead of ~800MB) - recommended for alpha testers
git clone --depth 1 -b production https://github.com/mediajunkie/piper-morgan-product.git
cd piper-morgan-product
./scripts/alpha-setup.sh
# Script will:
# → Check requirements (Python 3.11/3.12, Docker, Git)
# → Create virtual environment
# → Install dependencies
# → Generate JWT secret automatically
# → Start Docker containers
# → Launch the setup wizard at http://localhost:8001/setup

For Windows (Command Prompt or PowerShell):

REM Fast clone (~91MB instead of ~800MB) - recommended for alpha testers
git clone --depth 1 -b production https://github.com/mediajunkie/piper-morgan-product.git
cd piper-morgan-product
.\scripts\alpha-setup.bat
REM Script will:
REM → Check requirements (Python 3.11/3.12, Docker, Git)
REM → Create virtual environment
REM → Install dependencies
REM → Generate JWT secret automatically
REM → Start Docker containers
REM → Launch the setup wizard at http://localhost:8001/setup

Manual Setup (If You Prefer Full Control)

# 1. Clone and setup (~2-3 min)
# --depth 1 gives you a fast ~91MB download (vs ~800MB full history)
git clone --depth 1 -b production https://github.com/mediajunkie/piper-morgan-product.git
cd piper-morgan-product
python3.12 -m venv venv && source venv/bin/activate
# Requires Python 3.11 or 3.12 - verify with: python --version

# 2. Install dependencies (~5-10 min first time, 216 packages)
python -m pip install --upgrade pip
pip install -r requirements.txt
# ☕ This downloads ~1GB of packages - good time for a coffee break

# 3. Configure environment variables (~1 min)
cp .env.example .env
# Edit .env and set JWT_SECRET_KEY:
# Generate a secure key: openssl rand -hex 32
# Add to .env: JWT_SECRET_KEY=your-generated-key-here
# Note: .env is gitignored and survives git pull operations

# 4. Start Docker containers (~10-30 min first time)
docker compose up -d
# First run downloads ~4GB of images (PostgreSQL, Redis, etc.)
# ☕ Another good coffee break opportunity
# Subsequent runs: instant (images are cached)

# 5. Run database migrations (~1-2 min)
python -m alembic upgrade head
# This creates/updates all database tables

# 6. Start server for first-time setup
python main.py
# → Opens http://localhost:8001/setup (GUI setup wizard)

# 7. Complete setup wizard (~2-5 min)
# → Navigate through visual setup screens
# → Configure API keys, create user account
# → See "Setup Wizard Walkthrough" below for details

# 8. Configure preferences (optional, ~2 min)
python main.py preferences
# → Answer 5 questions about your work style
# → Or skip and configure later via Settings page

# 9. Validate installation (optional)
python scripts/validate_install.py
# → Checks all components are working
# → Shows clear pass/fail status

Setup Wizard Walkthrough (New in 0.8.2)

The GUI setup wizard guides you through configuration with a visual interface:

Step 1: Welcome Screen

The setup wizard welcome screen explains what will be configured and gives you a clear starting point.

Setup wizard welcome screen

Step 2: System Health Check

Automatic validation of your system:

Setup wizard health check

Step 3: API Key Configuration

Configure your LLM API keys through a form interface. Much easier than pasting in the terminal - you can see what you’re typing, correct mistakes, and get immediate validation feedback.

Supports:

Setup wizard API key configuration

Step 4: User Account Creation

Create your admin account:

Setup wizard user account creation

Step 5: Setup Complete

Setup confirmation with next steps and quick links to start using Piper.

Setup wizard success screen

Alternative: Command-Line Setup

If you prefer the original command-line setup wizard:

python main.py setup
# → Follow prompts for:
#    - Username and email
#    - Secure password (min 8 chars, bcrypt-hashed)
#    - API keys (OpenAI/Anthropic/Gemini)

Both methods configure the same settings. Use whichever you’re comfortable with.

First Commands to Try

Via Chat Interface

# In Piper's chat interface:
"Hello, what can you help me with?"
"Add a todo: Test Piper Morgan"
"What tasks do I have?"
"Upload a document and summarize it"

Via UI Features

After logging in to http://localhost:8001:

  1. Lists Management → Click “Lists” → “Create New List”
    • Add list name and description
    • Try sharing with another user (if multi-user testing)
  2. Todos Management → Click “Todos” → “Create New Todo”
    • Full CRUD operations
  3. File Upload/Download → Click “Files” → Upload a file
    • Supports: PDF, DOCX, TXT, MD, JSON (max 10MB)
    • Download and delete files
  4. Daily Standup → Click “Standup” → “Generate Standup”
    • AI-powered standup generation (2-3 seconds)
  5. Logout → Click user menu (top right) → “Logout”
    • Token revocation and logout working
  6. Permission Management → Try conversational commands:
    • “share my project plan with alex@example.com as editor”
    • “who can access my shopping list?”

Testing Focus for 0.8.6

What’s Stable (light testing recommended):

Where to Focus Testing (these need your attention):

If Something Breaks

Docker not running?

docker --version  # Should show version
docker ps         # Should show containers
# If not: Start Docker Desktop

Port 8001 taken?

lsof -i :8001     # See what's using it
kill -9 [PID]     # Kill it

Database/migration issues?

# If setup wizard fails with "column does not exist" error:
python -m alembic upgrade head

# If alembic command not found (not in venv):
source venv/bin/activate
alembic upgrade head

# Verify database is running:
docker ps | grep postgres
# Should show: piper-postgres running on port 5433

# Reset database completely (WARNING: deletes all data):
docker compose down -v
docker compose up -d
python -m alembic upgrade head

API key issues?

# Web UI method (easier):
# Navigate to http://localhost:8001/setup
# Re-enter your API keys in the form

# Or command-line method:
python main.py setup  # Re-run setup wizard
python main.py status # Verify keys

Login issues?

# Forgot password? Re-run setup to create new account
python main.py setup

# Can't access http://localhost:8001?
# Check server is running: python main.py
# Try: http://127.0.0.1:8001

Windows: localhost doesn’t work?

Problem: http://localhost:8001 gives connection error, but http://127.0.0.1:8001 works.

Why: Windows may resolve localhost to IPv6 (::1) while Piper binds to IPv4 (127.0.0.1).

Solution: Use http://127.0.0.1:8001 instead of localhost:8001 on Windows.

Environment variables not loading after git pull?

# Your .env file is gitignored and NEVER deleted by git operations
# If you see JWT_SECRET_KEY warnings after pulling new code:

# 1. Verify .env exists:
ls -la .env

# 2. If missing, CREATE it (this is required for all setups):
cp .env.example .env

# Edit .env in your IDE or text editor and add:
# JWT_SECRET_KEY=<paste-generated-key-here>

# Generate the key:
openssl rand -hex 32

# 3. Restart server:
python main.py

# Note: .env survives git pull, checkout, merge - git never touches it
# If you never created .env, that's the issue - Step 2 above is mandatory
# The setup wizard stores API keys separately (in secure keyring)

Commands not found after restarting terminal?

If python main.py gives errors like “No module named…” or commands aren’t found:

# You need to reactivate your virtual environment!
# The venv deactivates when you close your terminal.

# Mac/Linux:
cd piper-morgan-product
source venv/bin/activate

# Windows PowerShell:
cd piper-morgan-product
.\venv\Scripts\Activate.ps1

# Windows Command Prompt:
cd piper-morgan-product
venv\Scripts\activate.bat

# Your prompt should now show (venv) - try your command again
python main.py

Key Commands Reference

⚠️ Important: All commands must be run inside an activated virtual environment!

Activate venv each time you open a new terminal:

# Mac/Linux:
source venv/bin/activate

# Windows PowerShell:
.\venv\Scripts\Activate.ps1

# Windows Command Prompt:
venv\Scripts\activate.bat

Your prompt should show (venv) when activated.

python main.py              # Start server (opens browser automatically)
python main.py setup        # CLI setup wizard (alternative to GUI)
python main.py preferences  # Configure your preferences
python main.py status       # System health check
python main.py --verbose    # Show detailed logs
python main.py --no-browser # Don't auto-open browser

UI Navigation (After Server Starts)

After python main.py starts the server at http://localhost:8001:

What’s Working in 0.8.6

✅ MUX-IMPLEMENT Complete (0.8.5):

✅ Integration Dashboard & OAuth:

✅ Setup & Onboarding:

✅ Authentication & Security:

✅ Core Features:

✅ User Interface (Stable):

✅ Quality Validation:

See ALPHA_KNOWN_ISSUES.md for complete status and known limitations.

Getting Help

Remember

This is alpha software (0.8.6). Expect bugs. Don’t use for production. You’re responsible for API costs. See ALPHA_AGREEMENT_v2.md for details.

Testing Focus: Conversational naturalness is the focus. Does Piper feel like a colleague? Do follow-ups, compound queries, and soft offers work naturally?

Happy testing! 🚀

Last Updated: February 11, 2026