Skip to main content
📋How-To Guide

Upgrading prAxIs OS

Keep your prAxIs OS installation up-to-date with new features, standards, and improvements.

Quick Upgrade​

There are two ways to upgrade prAxIs OS:

The simplest way for most users:

# In Cursor, say:
"Run the prAxIs OS upgrade workflow"

The AI will use the praxis_os_upgrade_v1 workflow to safely upgrade your installation with automatic backup and validation.

Total Time: ~3-4 minutes

2. Standalone Script​

For direct command-line upgrades:

# Download and run directly (recommended - always latest)
curl -sSL https://raw.githubusercontent.com/honeyhiveai/praxis-os/main/dist/scripts/upgrade-praxis-os.py | python3 - /path/to/your/project

# Or download first, then run
curl -O https://raw.githubusercontent.com/honeyhiveai/praxis-os/main/dist/scripts/upgrade-praxis-os.py
python3 upgrade-praxis-os.py /path/to/your/project

# Upgrade from local praxis-os source (for development)
python3 upgrade-praxis-os.py /path/to/your/project --source /path/to/praxis-os

# Skip dependency updates (faster, for testing)
python3 upgrade-praxis-os.py /path/to/your/project --skip-deps

Total Time: ~2-3 minutes

The praxis_os_upgrade_v1 workflow provides a safe, automated upgrade process.

Workflow Under Review

The workflow is being updated to leverage the new standalone script capabilities. Check the Standalone Script section below for the latest upgrade features.

Start the Workflow​

# Via MCP tools
pos_workflow(
    action="start",
    workflow_type="praxis_os_upgrade_v1",
    target_file="ouroboros",
    options={
        "source_path": "/path/to/praxis-os",  # Or GitHub URL
        "dry_run": false,
        "auto_restart": true
    }
)

What Gets Upgraded​

The workflow updates:

  1. Universal Standards (.praxis-os/standards/universal/)

    • Concurrency patterns
    • Architecture patterns
    • Testing strategies
    • Failure modes
    • Security patterns
    • MCP tool guides
    • Operating model
    • Update procedures

  2. Workflows (.praxis-os/workflows/)

    • spec_creation_v1
    • spec_execution_v1
    • praxis_os_upgrade_v1
    • Any new workflows

  3. MCP Server (.praxis-os/ouroboros/)

    • Server code
    • Dependencies
    • Bug fixes
    • New features

  4. Configuration

    • .gitignore entries (auto-updates from standards)
    • Version tracking

What's Preserved​

Your customizations are never overwritten:

  • ✅ User Specs (.praxis-os/specs/) - Completely untouched
  • ✅ Development Standards (.praxis-os/standards/development/) - Your language-specific standards
  • ✅ Project Configuration - .cursorrules, mcp.json

Upgrade Process​

Phase 0: Pre-Flight Checks (30s)​

Validates everything before starting:

  • Source repository exists and is valid
  • Target installation is healthy
  • Sufficient disk space (~500MB)
  • No concurrent upgrades running
  • Git status is clean (if in git repo)

Phase 1: Backup & Preparation (20s)​

Creates safety net:

  • Timestamped backup: .praxis-os.backup.YYYYMMDD_HHMMSS/
  • Checksum manifest for validation
  • Upgrade lock to prevent concurrent upgrades

Phase 2: Content Upgrade (60s)​

Updates standards, usage, workflows:

  • Dry-run first (preview changes)
  • Actual upgrade with rsync
  • Updates .gitignore from standards
  • Verifies checksums

Safety: User-writable directories use rsync -av (NO --delete flag) to preserve your files.

Phase 3: MCP Server Upgrade (60s)​

Updates server code and dependencies:

  • Copies new MCP server code
  • Updates Python dependencies
  • Runs post-install steps (Playwright, etc.)
  • Restarts MCP server (Cursor must be restarted)
Server Restart

After Phase 3, you must restart Cursor to reload the MCP server. The workflow automatically saves its state and resumes after restart.

Phase 4: Post-Upgrade Validation (30s)​

Verifies everything works:

  • MCP tools registered correctly
  • RAG search operational
  • Browser tools functional
  • Workflow execution working

Phase 5: Cleanup (15s)​

Finishes up:

  • Releases upgrade lock
  • Archives old backups (if any)
  • Generates upgrade report
  • Updates version tracking

Rollback​

If anything goes wrong, automatic rollback restores from backup:

Automatic Rollback​

If any phase fails (2, 3, or 4), the workflow automatically:

  1. Stops immediately
  2. Restores from .praxis-os.backup.*/
  3. Releases upgrade lock
  4. Reports what failed

Target rollback time: < 30 seconds

Manual Rollback​

If you need to manually rollback:

# Stop MCP server (restart Cursor)

# Restore from backup
rm -rf .praxis-os
mv .praxis-os.backup.YYYYMMDD_HHMMSS .praxis-os

# Restart Cursor to reload MCP server

Version Tracking​

prAxIs OS tracks what's installed:

# Check current version
cat .praxis-os/VERSION.txt

# Shows:
# version_installed=2025-10-08T12:00:00Z
# version_updated=2025-10-08T14:30:00Z
# commit=a1b2c3d
# source=/path/to/praxis-os

Upgrade Frequency​

When to Upgrade​

Upgrade when:

  • 🆕 New features are released (check GitHub releases)
  • 🐛 Bug fixes for issues you're experiencing
  • 📚 New standards for technologies you use
  • 🔄 New workflows that match your needs

When NOT to Upgrade​

Skip upgrading when:

  • ⏰ In the middle of critical work
  • 🔬 Running important tests/experiments
  • 📝 Working on complex specs (finish first)

Standalone Script (Advanced)​

The scripts/upgrade-praxis-os.py script provides direct command-line access to the upgrade system.

When to Use the Script​

Use the standalone script when:

  • 🤖 CI/CD pipelines - Automated upgrades in deployment scripts
  • 🔧 Manual control - You want direct control over the upgrade process
  • ⚡ Speed - Skip workflow overhead (~1 minute faster)
  • 🧪 Testing - Dry-run upgrades before workflow execution

Script Usage​

# Download and run directly (recommended - always latest)
curl -sSL https://raw.githubusercontent.com/honeyhiveai/praxis-os/main/dist/scripts/upgrade-praxis-os.py | python3 - /path/to/your/project

# Or download first, then run with options
curl -O https://raw.githubusercontent.com/honeyhiveai/praxis-os/main/dist/scripts/upgrade-praxis-os.py
python3 upgrade-praxis-os.py /path/to/your/project --source /path/to/praxis-os  # Local source
python3 upgrade-praxis-os.py /path/to/your/project --skip-deps                  # Skip pip install

Note: The script is self-contained (stdlib only) and can be run immediately without any dependencies.

What the Script Does​

The script performs the same operations as the workflow:

  1. Validation - Pre-flight checks (Python version, disk space, etc.)
  2. Backup - Creates timestamped backup with checksums
  3. Content Upgrade - Updates standards, workflows, usage docs
  4. MCP Server Upgrade - Updates ouroboros code
  5. Dependency Update - Runs pip install -r requirements.txt (unless --skip-deps)
  6. Verification - Validates checksums and structure
  7. Cleanup - Archives old backups, generates report

Script vs. Workflow​

FeatureStandalone ScriptWorkflow
Speed~2-3 minutes~3-4 minutes
Backup✅ Automatic✅ Automatic
Rollback✅ Automatic✅ Automatic
MCP Restart⚠️ Manual✅ Automatic
Resume After Restart❌ No✅ Yes
AI Guidance❌ No✅ Yes
CI/CD Friendly✅ Yes❌ No
When to use which?
  • Workflow: Best for interactive upgrades in Cursor with AI assistance
  • Script: Best for automated deployments, CI/CD, or when you want direct control

CLI Options​

python scripts/upgrade-praxis-os.py --help

Available options:

  • target_dir (required) - Path to project directory containing .praxis-os/
  • --source PATH - Path to local praxis-os source (default: clone from GitHub)
  • --skip-deps - Skip pip install -r requirements.txt (faster, content-only upgrade)

Examples​

# Upgrade from GitHub latest (most common)
cd /path/to/your/project
python scripts/upgrade-praxis-os.py .

# Upgrade from local development copy
python scripts/upgrade-praxis-os.py . --source ~/dev/praxis-os

# Content-only upgrade (skip dependency installation)
python scripts/upgrade-praxis-os.py . --skip-deps

# Upgrade multiple projects
for project in project-a project-b project-c; do
    python scripts/upgrade-praxis-os.py "$project"
done

Troubleshooting Script Upgrades​

"Target directory does not exist"

Fix: Provide absolute or correct relative path

python scripts/upgrade-praxis-os.py /full/path/to/project

"Not a praxis-os installation"

Fix: Directory must contain .praxis-os/ directory

ls .praxis-os  # Should exist

"Upgrade failed: checksums don't match"

Fix: Corruption detected, rollback automatic

# Backup is at: .praxis-os.backup.YYYYMMDD_HHMMSS/
# Restoration happens automatically on failure

Manual Upgrade (Legacy)​

If you need manual control:

1. Backup Current Installation​

cp -r .praxis-os .praxis-os.backup.$(date +%Y%m%d_%H%M%S)

2. Pull Latest Source​

# If you have local clone
cd /path/to/praxis-os
git pull origin main

# Or fresh clone
git clone https://github.com/honeyhiveai/praxis-os.git /tmp/praxis-os-latest

3. Update Content​

# Update standards (prAxIs OS owned)
rsync -av --delete praxis-os/universal/standards/ .praxis-os/standards/universal/

# Update workflows
rsync -av --delete praxis-os/universal/workflows/ .praxis-os/workflows/

4. Update MCP Server​

# Copy server code
rsync -av --delete praxis-os/dist/ouroboros/ .praxis-os/ouroboros/

# Update dependencies
cd .praxis-os
./venv/bin/pip install -r ouroboros/requirements.txt

# Restart Cursor

5. Update .gitignore​

# Check for new required entries
# See: .praxis-os/standards/universal/installation/gitignore-requirements.md

Troubleshooting​

"Upgrade failed in Phase 2"​

Cause: File conflicts or permission issues

Fix:

  1. Check error message in upgrade report
  2. Manually resolve conflicts
  3. Re-run workflow

"MCP server won't start after upgrade"​

Cause: Dependency mismatch or Python version

Fix:

# Rebuild virtualenv
rm -rf .praxis-os/venv
cd .praxis-os
python -m venv venv
./venv/bin/pip install -r ouroboros/requirements.txt

# Restart Cursor

"Workflow says concurrent upgrade running"​

Cause: Previous upgrade didn't complete

Fix:

# Remove stale lock
rm -f .praxis-os/.upgrade_lock

# Re-run workflow

"Backup directory is huge"​

Cause: Backups include vector index cache

Fix:

# Check backup size
du -sh .praxis-os.backup.*

# Safe to delete after 7 days of stable operation
rm -rf .praxis-os.backup.20251001_*

Note: Backups are NOT committed to git (in .gitignore)

What's New in Each Version​

v1.5.0 (October 8, 2025)​

Added:

  • .gitignore management (prevents 2.7GB of ephemeral files)
  • Workflow execution via pos_workflow MCP tool
  • current_date MCP tool for preventing date errors
  • Installation step 04: gitignore configuration
  • Single source of truth for gitignore requirements

Fixed:

  • CRITICAL: Removed dangerous --delete from user-writable directories
  • Phase 2 now safely preserves user documentation

Changed:

  • Installation steps: 5 → 6 (added gitignore)
  • Upgrade Phase 2: 3 → 4 tasks
  • Total upgrade time: 3min 20s → 3min 35s

v1.4.0 (October 7, 2025)​

Added:

  • Modular MCP server architecture
  • Selective tool loading (performance optimization)
  • Tool count monitoring (warns at >20 tools)

Changed:

  • Configuration management with validation
  • Dependency injection throughout
  • Entry point simplified

Earlier Versions​

See CHANGELOG.md for complete history.

Best Practices​

Before Upgrading​

  1. ✅ Commit your work - Clean git status
  2. ✅ Finish active specs - Complete what you're working on
  3. ✅ Note your version - Check VERSION.txt before upgrade
  4. ✅ Read release notes - Know what's changing

After Upgrading​

  1. ✅ Restart Cursor - Reload MCP server
  2. ✅ Test MCP tools - Quick search_standards query
  3. ✅ Verify workflows - Check workflow list
  4. ✅ Review changes - See upgrade report
  5. ✅ Delete backup after 7 days - If no issues

Regular Maintenance​

  • 📅 Check for updates monthly
  • 🧹 Clean old backups quarterly
  • 📊 Review upgrade reports
  • 🔍 Monitor MCP server logs