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:    app_fib123
  Name:      FibCalc
  Platforms: win-x64

2b. Upload and Protect

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

Output:

Uploading artifact... done (2.4 MB)
Protection job queued.
  Build ID: build_abc789
  Status:   QUEUED

2c. Wait for Completion

pylocket status --build build_abc789

The status progresses through these stages:

Status	Meaning
QUEUED	Job is in the protection queue
PROCESSING	Bytecode extraction and encryption in progress
SCANNING	Malware scan running (if enabled)
PACKAGING	Re-packaging the protected artifact
READY	Protection complete — ready for download
FAILED	An error occurred (check the error message)

2d. Download the Protected Output

pylocket fetch --build build_abc789 --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
├── _pylocket_rt.pyd       # Native runtime (Windows)
│   (or _pylocket_rt.so)   # (Linux/macOS)
└── .pylocket_manifest     # Encrypted protection manifest

File	Purpose
myapp.exe	Your application with encrypted bytecode and injected bootstrap
_pylocket_rt	Native runtime that handles decryption, license validation, and anti-reverse-engineering
.pylocket_manifest	Cryptographically signed manifest mapping functions to their encrypted data

Important: All three files 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.

---

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