Documentation
Technical documentation for installing, configuring, and running the Pyvorin compiler.
Installation
RequirementsPython 3.10, 3.11, or 3.12 installed as python or python3.A working internet connection for licence activation and telemetry.Linux (glibc), macOS 12+, or Windows 10/11 on x86_64 or ARM64. Install from PyPIpip install pyvorinWe recommend installing inside a virtual environment:python -m venv .venv source .venv/bin/activate # Windows: .venv\Scripts\activate pip install pyvorin Verify the installpyvorin --version pyvorin doctorpyvorin doctor checks your Python version, platform support, network reachability, and licence daemon status. It does not transmit source code. Platform notesMost glibc-based Linux distributions are supported. musl-based distributions such as Alpine Linux may work but are not fully supported. macOS 12 and later work on Intel and Apple Silicon without Rosetta. Windows 10 version 2004 and later, and Windows 11, are supported. Uninstallpip uninstall pyvorin
Updated 1 month ago
What Pyvorin Is
Pyvorin is a Python-to-native compiler and runtime platform. It analyses standard Python code and attempts to produce native executables for supported workloads. When native compilation is not possible, Pyvorin falls back to a standard CPython interpreter so your program continues to run. Pyvorin is not a drop-in replacement for every Python runtime. It works best for self-contained scripts and packages that use the standard library or supported third-party wheels, have a clear entry point, and avoid runtime code generation such as exec or eval. Supported workloadsStandard library or supported third-party wheels.Stable types and clear control flow.A defined entry point such as app.py or a configured pyproject.toml/pyvorin.toml. Current limitationsNot every Python program can be compiled to native code. Unsupported constructs are recorded as fallback reasons and executed through CPython. Performance gains depend on the workload; some programs see large improvements, others see little or none. The CLI, licence system, and telemetry are production-ready. Edge runtime features are available through a separate SDK and runtime package.
Updated 1 month ago
Choosing a Plan
Pyvorin plans differ in compile credits, device limits, support level, and optional Edge entitlement. Review the Subscription page in the Portal to compare current plans. Consider your expected compile volume, team size, and whether you need priority support or Edge access. You can upgrade or downgrade from the same page. Changes typically take effect immediately or at the next billing cycle, depending on the provider.
Updated 1 month ago
Supported Platforms
Pyvorin supports the following platforms for the CLI and native compilation. Linux x86_64 and ARM64 (glibc-based distributions).macOS 12+ on Intel and Apple Silicon.Windows 10/11 x86_64 and ARM64. Platform support may expand over time. The output of pyvorin doctor shows whether your current system is supported.
Updated 1 month ago
System Requirements
Pyvorin runs on modern x86_64 and ARM64 systems. Before installing, confirm your environment meets the minimum requirements. RequiredPython 3.10, 3.11, or 3.12.Linux (glibc), macOS 12+, or Windows 10/11.At least 2 GB of free RAM for small projects; larger projects need more.An internet connection for activation and telemetry. Not supportedmusl-only Linux, 32-bit operating systems, and Windows versions older than Windows 10 version 2004 are not supported. Running inside a supported container on an unsupported host may also fail.
Updated 1 month ago
Portal Overview
The Pyvorin Portal is the customer-facing dashboard for managing your account, licences, billing, and support. Main sectionsDashboard — usage summary, recent compiles, and credit balance.Licences — licence keys and active devices.Billing — invoices, payment methods, and subscription.Support — support tickets and responses.API Tokens — personal access tokens for the Customer API. Most actions can be performed without contacting support. Use the search bar or documentation links to find help.
Updated 1 month ago
Creating an Account
You need a Pyvorin account to manage licences, billing, support tickets, and API tokens. Sign upVisit crm.pyvorin.com/register, enter your email, name, and password, then confirm your email address. You can also sign up through an organisation invitation. After registrationOnce signed in, you can add a billing address, view your subscription, create licence keys, and generate API tokens. Two-factor authentication can be enabled from the Security page.
Updated 1 month ago
Quickstart Guide
This guide walks you from account creation to your first native compile. Create a Pyvorin account at crm.pyvorin.com/register.Install the CLI with pip install pyvorin.Activate your licence key from the Licence Keys page.Run pyvorin compile app.py --report inside your project.Review the report and run the output binary. For help at any step, run pyvorin doctor or open a support ticket from the Portal.
Updated 1 month ago
First Compile
After installing Pyvorin and activating your licence, you can compile a Python file. Basic compilepyvorin compile app.pyPyvorin analyses app.py, attempts native compilation, and writes output to the build directory configured in pyvorin.toml (default ./build). What happens during compilationThe CLI validates your licence and device token.Pyvorin parses and type-infers your code.Supported modules are compiled to native code.Unsupported constructs are marked for fallback and executed by CPython at runtime.Compile metrics are sent to the Portal. Viewing resultspyvorin compile app.py --reportThe report shows native coverage percentage, fallback reasons, compile duration, and credits used. Successful compiles deduct 1 credit; error compiles do not. Run the output./build/appIf the build fell back entirely to CPython, the output script runs as normal Python.
Updated 1 month ago
Authentication
Pyvorin uses the Pyvorin Portal to authenticate devices and licence keys. The CLI supports web-based device activation and licence-key activation. Device activation flowRun pyvorin auth login.The CLI displays a device code and a URL such as https://crm.pyvorin.com/device.Open the URL, sign in to your Pyvorin account, and enter the code.The CLI polls until you approve the request.Once approved, the CLI stores a device token locally. Licence-key activationRun pyvorin auth activate --key PYV-XXXX-XXXX-XXXX.The CLI sends your device token and licence key to the Portal.The server returns a long-lived licence device token if the key is valid and within its device limit. Token expiry and refreshDevice authorization codes expire after 10 minutes. Licence device tokens can be refreshed with pyvorin auth refresh. If a token expires or is revoked, the CLI requests re-authentication. RevocationYou can revoke a device from the Licences page in the Portal. Once revoked, the device token is invalid and the CLI must re-authenticate. Revocation takes effect immediately for new requests.
Updated 1 month ago
Customer API Overview
The Customer API lets you query and manage your account programmatically. Key endpoints include GET /me for profile, GET /subscription for subscription status, GET /invoices for billing history, GET /licence-keys for licence keys, and GET /support-tickets plus POST /support-tickets for support. All requests require a valid API token in the Authorization: Bearer <token> header.
Updated 1 month ago
Token Storage
Device tokens and API tokens are stored securely on your machine. CLI tokens live in the Pyvorin configuration directory and are not printed to logs. API tokens are hashed in the Portal database; only the plaintext value is shown once at creation. If a machine is lost or compromised, revoke its device from the Portal and rotate any API tokens created from that account.
Updated 1 month ago
API Tokens
API tokens let you access the Customer API from scripts and integrations. Creating a tokenSign in to the Portal.Go to API Tokens.Click Create Token.Choose abilities: read or read-write.Copy the plaintext token immediately; it is shown only once. SecurityStore tokens in a secret manager or environment variable. Rotate tokens periodically. If a token is leaked, revoke it from the Portal immediately.
Updated 1 month ago
Rate Limits
Pyvorin APIs enforce rate limits to protect platform stability. Compiler endpoints are rate-limited per route.Customer API endpoints are rate-limited per authenticated user.Webhook endpoints are rate-limited under the webhooks limiter. If you exceed a limit, the response is HTTP 429. Retry after the interval specified in the Retry-After header, or contact support if you need a higher limit.
Updated 1 month ago
Report Bug Command
The report-bug command opens a support ticket with useful diagnostics. pyvorin report-bug --title "Title" --logs By default, source code is not attached and command text is redacted. You can attach additional files manually after the ticket is created.
Updated 1 month ago
Verbose Output
Run compiles with --verbose to see detailed progress. pyvorin compile app.py --verbose Verbose output shows each compiled module, fallback decisions, and timing. This is useful when a compile fails or produces unexpected fallback results.
Updated 1 month ago
Troubleshooting
This page lists common problems and how to resolve them. CLI cannot connectVerify internet access: curl https://crm.pyvorin.com/health.Check proxy settings; the CLI respects HTTP_PROXY and HTTPS_PROXY.Run pyvorin doctor for a structured diagnosis. Licence activation failsConfirm the key is typed correctly.Check the device limit on the Portal Licences page.Revoke unused devices if you have reached the limit.Ensure the key has not expired. Compilation failsRun with --verbose to see the failing module.Switch to --mode=safe to allow more fallbacks.Check that all dependencies are installed in the active virtual environment.Review compiler errors in the Portal Usage page. Low native coverageUse the fallback report to identify constructs to refactor.Add type hints and avoid dynamic types.Whitelist supported extensions in native.extensions. Credits not updatingCredits refresh with the billing cycle.Successful compiles deduct 1 credit; errors do not.Check the Portal Usage page for details. Still blocked?Open a support ticket from the Portal after signing in. Include the output of pyvorin doctor and any fallback or error reports.
Updated 1 month ago
API Documentation
Pyvorin exposes two public APIs: the Compiler API for CLI authentication and telemetry, and the Customer API for managing subscriptions, invoices, licences, and support tickets. Compiler API v1Base URL: https://crm.pyvorin.com/compiler/v1. Endpoints are rate-limited. Authenticated endpoints expect a licence device token in the Authorization: Bearer <token> header. Customer API v1Base URL: https://crm.pyvorin.com/api/v1/customer. Requires a Sanctum personal access token with read or read-write ability. Tokens are created from the API Tokens page. Rate limitsCompiler endpoints, Customer API endpoints, and webhook endpoints each have separate rate limits. If you receive a 429 response, reduce request frequency or contact support.
Updated 1 month ago
Webhooks
The Pyvorin Portal receives webhooks from payment providers and inbound email services. These webhooks update billing and support records automatically. Supported inbound webhook endpoints include Stripe billing events, Paddle billing events, and inbound support email events. At this time, customer accounts cannot register custom webhook URLs. Event notifications are delivered through the Portal dashboard, email, and optional Telegram integration.
Updated 1 month ago
Webhook Security
Inbound webhook endpoints are protected by provider signatures and rate limits. Stripe and Paddle signatures are verified using provider secrets.Webhook endpoints are rate-limited under the webhooks limiter.Inbound email can be gated by allowed sender domains. If you suspect a forged webhook, contact support with the delivery identifier.
Updated 1 month ago
Edge and Edge SDK
Pyvorin Edge is a separate runtime and SDK for deploying compiled Python to edge environments. It is not included in the core Pyvorin CLI package. What is Pyvorin Edge?Pyvorin Edge targets constrained, low-latency environments such as CDN workers, IoT gateways, and on-premise edge nodes. It uses the same compiler frontend as Pyvorin but emits artifacts suited to the edge runtime. Edge SDKThe Edge SDK is distributed as a separate package. It provides edge-specific build profiles, deployment helpers for supported edge platforms, and runtime telemetry. Build modeSet build.mode = "edge" in pyvorin.toml when building for edge targets. This adjusts binary size, startup time, and runtime dependencies. Edge support is available to eligible plans. Contact support to confirm Edge entitlement for your subscription.
Updated 1 month ago
Edge Build Mode
The edge build mode prepares your project for the Pyvorin Edge runtime. [build] mode = "edge" This mode favors small binary size and fast cold starts over raw throughput. Some Python constructs that are supported in balanced mode may fall back in edge mode. Edge artifacts are deployed through the separate Edge SDK. The Portal tracks Edge licence keys and usage if your plan includes Edge.
Updated 1 month ago
Security Overview
Security is built into Pyvorin through authentication, rate limiting, and privacy-conscious telemetry. Account securityUse a strong, unique password.Enable two-factor authentication from the Security page.Review active devices and revoke any you do not recognize. Reporting security issuesEmail security@pyvorin.com or open a confidential support ticket. Do not disclose vulnerabilities in public channels.
Updated 1 month ago
Reading Compile Logs
Compile logs are stored in the Pyvorin data directory on your machine. Each log entry includes the command hash, compile status, duration, native coverage, and fallback reasons. Logs do not contain source code unless you explicitly opt in. Use pyvorin logs to list recent logs and pyvorin logs --tail to view the most recent entries.
Updated 1 month ago