QUICKSTART.md

SAAP Quick Start Guide

satware Autonomous Agent Platform (SAAP) - Local multi-agent orchestration platform

⚠️ CRITICAL SECURITY NOTICE

Before running the project, you MUST remediate hardcoded API keys!

The imported codebase contains 40+ hardcoded API keys that must be replaced with environment variables before:

• Running the application
• Pushing to GitHub
• Deploying to any environment

📋 Action Required: See SECURITY_REMEDIATION_REQUIRED.md for detailed remediation steps.

---

Prerequisites

Required Software

1. Python 3.10 or higher

   python3 --version  # Should be 3.10+
   

2. Node.js 18 or higher

   node --version  # Should be v18+
   npm --version
   

3. PostgreSQL Database

   psql --version
   

   • Installation: https://www.postgresql.org/download/

4. Git (for version control)

   git --version
   

Optional (Recommended)

• Redis (for caching and message queuing)
• Docker (for containerized deployment)
• Docker Compose (for multi-service orchestration)

---

Installation Steps

1. Clone the Repository

git clone https://github.com/satwareAG/saap.git
cd saap

2. Backend Setup

2.1 Create Python Virtual Environment

# Create virtual environment
python3 -m venv .venv

# Activate it
source .venv/bin/activate  # On Linux/macOS
# OR
.venv\Scripts\activate  # On Windows

2.2 Install Python Dependencies

pip install --upgrade pip
pip install -r requirements.txt

2.3 Configure Environment Variables

# Copy the example environment file
cp backend/.env.example backend/.env

# Edit the .env file with your settings
nano backend/.env  # or use your preferred editor

Required Configuration:

# Database
DATABASE_URL=postgresql://user:password@localhost:5432/saap_db

# AI Provider API Keys (⚠️ SECURITY: Never commit these!)
OPENROUTER_API_KEY=your_openrouter_api_key_here
COLOSSUS_API_KEY=your_colossus_api_key_here

# Application Settings
DEBUG=True
LOG_LEVEL=INFO

2.4 Set Up Database

# Create PostgreSQL database
createdb saap_db

# Run migrations (if applicable)
cd backend
alembic upgrade head
cd ..

3. Frontend Setup

3.1 Install Node.js Dependencies

cd frontend
npm install
cd ..

---

Starting the Application

Option 1: Using Startup Scripts (Recommended)

Start Backend

./start_backend.sh

The backend will be available at:

• API: http://localhost:8000
• API Docs (Swagger): http://localhost:8000/docs
• API Docs (ReDoc): http://localhost:8000/redoc

Start Frontend (in a new terminal)

./start_frontend.sh

The frontend will be available at:

• Application: http://localhost:5173

Option 2: Manual Start

Start Backend Manually

# Activate virtual environment
source .venv/bin/activate  # Linux/macOS
# OR
.venv\Scripts\activate  # Windows

# Load environment variables
export $(cat backend/.env | grep -v '^#' | xargs)

# Start server
cd backend
python -m uvicorn main:app --reload --host 0.0.0.0 --port 8000

Start Frontend Manually

cd frontend
npm run dev

---

Verifying the Installation

1. Check Backend Health

curl http://localhost:8000/health
# Expected: {"status": "healthy"}

2. Access API Documentation

Open in browser: http://localhost:8000/docs

3. Access Frontend Application

Open in browser: http://localhost:5173

---

Project Structure

saap/
├── backend/                    # Python FastAPI Backend
│   ├── agents/                 # AI Agent implementations
│   │   ├── colossus_agent.py   # Colossus (local) agent
│   │   └── openrouter_agent*.py # OpenRouter agents
│   ├── api/                    # API endpoints
│   ├── database/               # Database models & services
│   ├── services/               # Business logic services
│   ├── .env.example            # Environment template
│   └── main.py                 # FastAPI application entry
│
├── frontend/                   # Vue.js 3 Frontend
│   ├── src/
│   │   ├── components/         # Vue components
│   │   ├── views/              # Page views
│   │   ├── stores/             # Pinia state management
│   │   └── services/           # API client services
│   ├── package.json
│   └── vite.config.js          # Vite configuration
│
├── start_backend.sh            # Backend startup script
├── start_frontend.sh           # Frontend startup script
├── requirements.txt            # Python dependencies
└── README.md                   # Full documentation

---

Common Issues & Troubleshooting

Issue: ModuleNotFoundError when starting backend

Solution: Ensure virtual environment is activated and dependencies installed:

source .venv/bin/activate
pip install -r requirements.txt

Issue: Port already in use (8000 or 5173)

Solution: Kill the process using the port:

# Find process using port 8000
lsof -i :8000  # or: netstat -tulpn | grep 8000

# Kill the process
kill -9 <PID>

Issue: Database connection errors

Solution:

1. Verify PostgreSQL is running: systemctl status postgresql
2. Check DATABASE_URL in backend/.env
3. Ensure database exists: createdb saap_db

Issue: Frontend shows "Network Error"

Solution:

1. Verify backend is running on port 8000
2. Check CORS settings in backend/main.py
3. Check browser console for specific errors

Issue: Hardcoded API keys detected

Solution:

1. DO NOT push to GitHub yet!
2. Follow SECURITY_REMEDIATION_REQUIRED.md
3. Replace all hardcoded keys with environment variables
4. Re-scan with Gitleaks: gitleaks detect --no-git

---

Development Workflow

Running Tests

Backend Tests:

cd backend
pytest

Frontend Tests:

cd frontend
npm test

Code Quality Checks

Backend (Python):

# Linting
ruff check .

# Type checking
mypy backend/

Frontend (JavaScript/TypeScript):

cd frontend
npm run lint

---

Security Best Practices

🔒 Essential Security Rules

1. Never commit API keys to version control
2. Always use environment variables for sensitive data
3. Run Gitleaks before every commit:

   gitleaks detect --no-git
   

4. Update dependencies regularly:

   pip list --outdated  # Python
   npm outdated         # Node.js
   

5. Use strong passwords for database and services
6. Enable HTTPS in production environments

---

Next Steps

After successful startup:

1. ✅ Complete Security Remediation (see SECURITY_REMEDIATION_REQUIRED.md)
2. ✅ Configure all agents in the dashboard
3. ✅ Test agent orchestration with sample tasks
4. ✅ Review API documentation at http://localhost:8000/docs
5. ✅ Set up development database with test data
6. ✅ Configure Redis/RabbitMQ (optional, for advanced features)

---

Additional Resources

• Full Documentation: README.md
• Security Remediation: SECURITY_REMEDIATION_REQUIRED.md
• Import Notes: IMPORT_NOTES.md
• API Documentation: http://localhost:8000/docs (when running)
• Project Repository: https://github.com/satwareAG/saap

---

Support & Contact

• Student: Hanan Wandji Danga
• Organization: satware AG
• Project: Master's Thesis - SAAP Platform
• Timeline: 2025-09-15 to 2026-03-14

For issues or questions, please create an issue on the GitHub repository.

---

Last Updated: 2025-11-11