Basic Tutorial

This tutorial walks you through the complete PyLocket protection workflow — from building your Python application to delivering a protected, license-gated artifact. It assumes you have already completed the Getting Started guide.

---

Overview

The protection workflow has four stages:

Build → Protect → License → Distribute

1. Build your Python application using a packaging tool (PyInstaller, cx_Freeze, etc.)
2. Protect the artifact with PyLocket
3. License your application by creating license keys for end-users
4. Distribute the protected artifact and license keys to customers

---

1. Build Your Application

For this tutorial, create a sample application:

# myapp.py
import sys

def calculate_fibonacci(n):
    """Calculate the nth Fibonacci number."""
    if n <= 1:
        return n
    a, b = 0, 1
    for _ in range(2, n + 1):
        a, b = b, a + b
    return b

def main():
    print("=== Fibonacci Calculator ===")
    print(f"Python {sys.version}")
    for i in [10, 20, 30, 40, 50]:
        result = calculate_fibonacci(i)
        print(f"  F({i}) = {result}")
    print("Done!")

if __name__ == "__main__":
    main()

Build it with PyInstaller:

pip install pyinstaller
pyinstaller --onefile myapp.py

This produces dist/myapp (or dist/myapp.exe on Windows).

Note: PyLocket supports multiple packaging formats. See the How-To Guides for format-specific instructions.

---

2. Protect the Artifact

2a. Register the Application (first time only)

pylocket apps create --name "FibCalc" --platform win-x64

Output:

App created successfully.
  App ID:    3f8a1c22-9b4e-4d17-a6f0-2c5e7d90b114
  Name:      FibCalc
  Platforms: win-x64

2b. Upload and Protect

pylocket protect \
  --app 3f8a1c22-9b4e-4d17-a6f0-2c5e7d90b114 \
  --artifact dist/myapp.exe \
  --platform win-x64 \
  --python 3.12

Output:

Uploading artifact... done (2.4 MB)
Protection job queued.
  Build ID: 7c2d5e91-0a36-4b8f-9e14-8d63f2a70c55
  Status:   pending

2c. Wait for Completion

pylocket status --build 7c2d5e91-0a36-4b8f-9e14-8d63f2a70c55

The status progresses through these stages:

Status	Meaning
pending	Job is in the protection queue
processing	Protection in progress
ready	Protection complete, ready for download
failed	An error occurred (check the error message)
rejected	The malware scan flagged the artifact; the developer account is auto-suspended pending review

Note: Finer-grained progress (scanning, packaging, etc.) is reported separately in the processing_stage field.

2d. Download the Protected Output

pylocket fetch --build 7c2d5e91-0a36-4b8f-9e14-8d63f2a70c55 --out dist/protected/

Your protected application is now in dist/protected/.

---

3. Understand the Output

The protected output directory contains:

dist/protected/
├── myapp.exe              # Protected executable
├── <native runtime>       # Platform-specific runtime library
└── <protection manifest>  # Encrypted protection manifest

File	Purpose
myapp.exe	Your application with encrypted bytecode and injected bootstrap
Native runtime	Handles decryption, license validation, and runtime integrity checks
Protection manifest	Cryptographically signed manifest mapping functions to their encrypted data

Important: All files in the protected output must be distributed together. The application will not run if any file is missing.

---

4. What Gets Protected

PyLocket operates at the function level. Every Python function in your application is individually encrypted with military-grade encryption:

• Function bodies are replaced so that decompilers cannot see your original logic
• Original bytecode is encrypted and stored securely in the manifest
• At runtime, each function is decrypted on-demand, executed, and then securely zeroed from memory
• Decompilers see only stub code, never your original logic

---

5. Run the Protected App

./dist/protected/myapp.exe

The application will:

1. Load the native runtime
2. Verify the cryptographic signature of the manifest
3. Prompt for a license key (or check for a cached token)
4. On valid activation, decrypt and execute functions on-demand

Without a valid license key, the application will display an activation error and exit.

What the End-User Sees

First run: The application prompts the end-user to enter their license key. The key is sent to the PyLocket activation API along with a device fingerprint. On success, a runtime token is cached locally.

Headless / CI use: Set the PYLOCKET_LICENSE_KEY environment variable to skip the interactive prompt:

export PYLOCKET_LICENSE_KEY="A7K2-M9P4-X3J8-W5N6"
./dist/protected/myapp.exe

Security note: Only use PYLOCKET_LICENSE_KEY in trusted environments (e.g., private CI runners, secure servers). Do not expose license keys in public logs or repositories.

Subsequent runs: The cached activation token is reused automatically -- no license key prompt appears as long as the token is valid.

Offline use: The application works offline for the duration of the configurable token expiry plus an offline grace period. After the grace period expires, the application requires an internet connection to re-activate.

---

6. Summary

In this tutorial you learned how to:

• Build a Python application with PyInstaller
• Register the application with PyLocket
• Protect the artifact with pylocket protect
• Monitor the build status with pylocket status
• Download the protected output with pylocket fetch
• Understand the protected output structure

---

Next Steps

Goal	Guide
Multi-platform builds and CI/CD integration	Advanced Tutorial
Publish for Windows, macOS, and Linux	Multi-OS Publishing
Set up licensing and distribution	Licensing Tutorial
CLI command details	CLI Reference