Advanced Tutorial

This tutorial covers advanced PyLocket features: multi-platform protection, CI/CD automation, and the PyCharm plugin. It builds on the Basic Tutorial.

---

Multi-Platform Protection

PyLocket supports five platform targets:

Platform ID	OS	Architecture
win-x64	Windows	x86_64
linux-x64	Linux	x86_64
linux-arm64	Linux	aarch64
mac-x64	macOS	x86_64 (Intel)
mac-arm64	macOS	Apple Silicon

Register Multiple Platforms

When creating an app, list all platforms you intend to ship:

pylocket apps create \
  --name "MyApp" \
  --platform win-x64 linux-x64 mac-arm64

Protect Each Platform Separately

Each platform artifact must be protected individually:

# Windows
pylocket protect \
  --app app_abc123 \
  --artifact dist/myapp.exe \
  --platform win-x64 \
  --python 3.12

# Linux
pylocket protect \
  --app app_abc123 \
  --artifact dist/myapp \
  --platform linux-x64 \
  --python 3.12

# macOS (Apple Silicon)
pylocket protect \
  --app app_abc123 \
  --artifact dist/myapp.app \
  --platform mac-arm64 \
  --python 3.12

Each platform produces its own Build ID. Track them independently:

pylocket status --build build_win_001
pylocket status --build build_linux_002
pylocket status --build build_mac_003

---

Python Version Targeting

PyLocket protects bytecode at the specific Python version level. Specify the version that was used to build your artifact:

pylocket protect \
  --app app_abc123 \
  --artifact dist/myapp.exe \
  --platform win-x64 \
  --python 3.11

Supported versions: 3.9, 3.10, 3.11, 3.12, 3.13

Important: The --python version must match the Python version used by your packaging tool (PyInstaller, cx_Freeze, etc.). A mismatch will cause bytecode decryption failures at runtime.

---

Automating Protection in CI/CD

PyLocket integrates into any CI/CD pipeline. Here is a GitHub Actions example:

# .github/workflows/protect.yml
name: Protect and Release

on:
  push:
    tags: ["v*"]

jobs:
  build-and-protect:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.12"

      - name: Install dependencies
        run: |
          pip install pylocket pyinstaller
          pip install -r requirements.txt

      - name: Build executable
        run: pyinstaller --onefile myapp.py

      - name: Login to PyLocket
        env:
          PYLOCKET_TOKEN: ${{ secrets.PYLOCKET_TOKEN }}
        run: pylocket login --token "$PYLOCKET_TOKEN"

      - name: Protect artifact
        run: |
          pylocket protect \
            --app ${{ vars.PYLOCKET_APP_ID }} \
            --artifact dist/myapp \
            --platform linux-x64 \
            --python 3.12

      - name: Wait for protection
        run: |
          BUILD_ID=$(pylocket status --app ${{ vars.PYLOCKET_APP_ID }} --latest --format json | jq -r '.build_id')
          while true; do
            STATUS=$(pylocket status --build "$BUILD_ID" --format json | jq -r '.status')
            if [ "$STATUS" = "READY" ]; then break; fi
            if [ "$STATUS" = "FAILED" ]; then echo "Protection failed"; exit 1; fi
            sleep 10
          done

      - name: Download protected output
        run: pylocket fetch --build "$BUILD_ID" --out dist/protected/

      - name: Upload release artifact
        uses: actions/upload-artifact@v4
        with:
          name: myapp-protected-linux-x64
          path: dist/protected/

For detailed CI/CD setup, see CI/CD Integration.

---

Using the PyCharm Plugin

The PyLocket PyCharm plugin lets you protect applications directly from the IDE.

Installation

1. Open PyCharm → Settings → Plugins → Marketplace
2. Search for "PyLocket"
3. Click Install and restart PyCharm

Usage

1. Open the PyLocket tool window (bottom panel)
2. Click Login and enter your credentials
3. The plugin auto-detects packaging configurations (PyInstaller spec files, setup.py, etc.)
4. Select an artifact and click Protect
5. Monitor the build status in the tool window
6. Click Download when the build is ready

For detailed instructions, see PyCharm Plugin.

---

Using the Developer Portal

The Developer Portal provides a web interface for managing your PyLocket apps:

• Dashboard: View all apps, recent builds, and license activity
• Apps: Create and configure applications
• Builds: View build history, status, and download protected artifacts
• Licenses: Create, monitor, and revoke end-user licenses
• Billing: View usage, invoices, and payment methods
• Settings: Manage API keys, 2FA, and account preferences

Everything available in the portal is also available through the CLI and REST API.

---

API Keys for Automation

For CI/CD and programmatic access, use API keys instead of interactive login:

1. Go to the Developer Portal → Settings → API Keys
2. Click Generate API Key
3. Store the key securely (e.g., as a CI/CD secret)

Use the key with any CLI command:

pylocket protect --token <API_KEY> --app ...

Or set it as an environment variable:

export PYLOCKET_TOKEN=<API_KEY>
pylocket protect --app ...

To rotate your API key:

pylocket auth api-keys rotate

Warning: Rotating an API key invalidates the previous key immediately. Update all CI/CD pipelines and scripts before rotating.

---

Two-Factor Authentication

Enable 2FA for your developer account for additional security:

# Start setup (returns a QR code for your authenticator app)
pylocket auth 2fa setup

# Confirm with a code from your authenticator
pylocket auth 2fa confirm --code 123456

# Check 2FA status
pylocket auth 2fa status

# Disable 2FA (requires current code)
pylocket auth 2fa disable --code 123456

When 2FA is enabled, pylocket login will prompt for a TOTP code after your password.

---

Summary

In this tutorial you learned how to:

• Protect applications for multiple platforms
• Target specific Python versions
• Automate protection in CI/CD pipelines
• Use the PyCharm plugin and Developer Portal
• Manage API keys and 2FA

---

Next Steps

Goal	Guide
Publish for all three OSes end-to-end	Multi-OS Publishing
Set up licensing and distribution	Licensing Tutorial
Choose a distribution strategy	Distribution Strategies
Format-specific protection guides	How-To Guides
Full CLI reference	CLI Reference