Hrunner

A lightweight Windows runtime and dependency manager for Python applications.

Hrunner separates the desktop application from its Python runtime and dependencies. A generated application contains a tiny native launcher, manifest, and application code, while Hrunner manages Python runtimes and shared dependencies on demand.

Overview
Why Hrunner?
Comparison
Architecture
How It Works
Installation
Quick Start
Build Your First Application
Builder Configuration
Build Parameters
Runtime Management
Package Management
Application Isolation
Manifest Format
CLI Reference
Hrunner Manager
Troubleshooting
FAQ
Architecture Details
Development
Building Hrunner
Testing
Contributing
Security
Roadmap
License

Overview

Traditional tools such as PyInstaller create large executables by bundling the full Python interpreter, standard library, and all installed packages into every standalone binary (typically 50–200 MB per application).

Hrunner takes a different approach:

Applications are distributed as tiny native executables (~4.7 MB) containing only the application's source code and a manifest.
The executable contains no Python runtime, no standard library, and no third-party packages.
The Hrunner Main App is installed on the user's PC via an NSIS installer and centrally manages Python runtimes and packages.
Applications communicate with Hrunner through local Windows Named Pipes (\\.\pipe\hrunner).
Packages are physically deduplicated in a central pool, yet logically isolated during execution.
Hrunner is never a persistent background daemon or service—it starts on demand when an application launches and shuts down automatically when idle.

Why Hrunner?

Ultra-Small Binaries: Output executables are ~4.7 MB instead of 100+ MB.
Lightning-Fast Builds: hbuild builds executables in under 10 milliseconds.
Shared Package Pool: If 5 applications use requests 2.32.5, it is downloaded and stored on disk only once.
Multi-Version Coexistence: App A can use numpy 1.26.4 while App B uses numpy 2.3.2 on the same machine without interference.
Polished Consumer Experience: First launch presents a clean native Windows dialog showing missing dependencies and download size, followed by automated installation.
Zero Web / Localhost Ports: 100% native Windows architecture with zero localhost HTTP servers, zero web sockets, and zero browser tabs.

Comparison

Feature	Hrunner	PyInstaller	PyApp
Output Binary Size	~4.7 MB	50 MB – 200 MB	25 MB – 60 MB
Build Time	< 10 ms	30 s – 120 s	5 s – 30 s
Dependency Sharing	Central pool (deduplicated)	None (duplicated per app)	None (isolated per app)
Multi-App Storage	Shared & reference-counted	Multiplied per application	Multiplied per application
Daemon / Service	None (on-demand auto-exit)	None	None
Management UI	Windows 11 Fluent Design	None	None
IPC Mechanism	Windows Named Pipes	N/A	N/A

Architecture

Hrunner consists of two distinct components:

┌────────────────────────────────────────────────────────┐
│               Hrunner Main App (End User)              │
│  Installed via NSIS to %LOCALAPPDATA%\Programs\Hrunner │
│                                                        │
│  ├── Windows Named Pipe Server (\\.\pipe\hrunner)      │
│  ├── Python Runtime Store (%LOCALAPPDATA%\Hrunner)     │
│  ├── Shared Package Pool (Physical Deduplication)      │
│  ├── Application Registry (registry.json)              │
│  ├── Native Windows TaskDialog Installer Flow          │
│  └── Windows 11 Fluent GUI (hmanager, DWM Mica)        │
└──────────────────────────▲─────────────────────────────┘
                           │ Windows Named Pipe
                           │ (\\.\pipe\hrunner)
┌──────────────────────────┴─────────────────────────────┐
│          Generated Application (hlauncher Stub)        │
│                                                        │
│  ├── Native Go Launcher Executable (~4.7 MB)          │
│  ├── Application Manifest (format_version: 1)          │
│  └── Embedded / Appended Application Python Code       │
└────────────────────────────────────────────────────────┘

Hrunner Main App: Installed on the user's PC via HrunnerSetup.exe. Manages the runtime store, shared package pool, registry, native Windows installer UI, and Named Pipe IPC server.
Hrunner Builder (hbuild): Developer CLI that analyzes Python projects, parses requirements.txt, generates manifests, and packages code into lightweight native executables.

How It Works

Developer Machine

Python Project
     │
     ▼
hbuild build ./myproject
     │
     ▼ (8 ms)
MyApplication.exe (~4.7 MB)

End User Machine

MyApplication.exe
     │
     ▼
Check \\.\pipe\hrunner
     │
     ├── Inactive ──> Start installed hrunner.exe --pipe-server
     └── Active ────> Connect to pipe
     │
     ▼
Send LaunchRequest (Manifest)
     │
     ▼
Hrunner checks Python runtime & packages
     │
     ├── Missing ──> Show native dialog -> Download & verify -> Install
     └── Ready   ──> Instant launch
     │
     ▼
Launch isolated Python process with tailored sys.path
     │
     ▼
Application exits ──> Pipe closes ──> Hrunner exits after 5s idle

Installation

For End Users

Download HrunnerSetup.exe from GitHub Releases.
Run HrunnerSetup.exe. It installs to %LOCALAPPDATA%\Programs\Hrunner and registers with the Windows shell.
Launch any application built with Hrunner.

For Developers (Building from Source)

# Clone the repository
git clone https://github.com/shs3131/H-runner.git
cd H-runner

# Compile the developer tools and core binaries
go build -ldflags="-s -w" -o hrunner.exe ./cmd/hrunner
go build -ldflags="-s -w" -o hlauncher.exe ./cmd/hlauncher
go build -ldflags="-s -w" -o hbuild.exe ./cmd/hbuild
go build -ldflags="-s -w" -o hmanager.exe ./cmd/hmanager

Quick Start

1. Create a Python Project

Create a directory with main.py and requirements.txt:

main.py:

import sys
import requests

print(f"Running Python {sys.version.split()[0]}")
print(f"Requests {requests.__version__} loaded successfully!")

requirements.txt:

requests == 2.32.5

2. Build the Application

hbuild build . --output MyApp.exe --name "My App" --version "1.0.0" --python "3.13.7"

3. Run the Executable

.\MyApp.exe

On first launch, Hrunner prompts the user to download Python 3.13.7 and requests 2.32.5, installs them into the shared pool, and starts the application. On subsequent launches, the application starts immediately.

Build Parameters

The hbuild build command supports the following parameters:

Parameter	Type	Default	Description
`--output`, `-o`	`string`	`<Name>.exe`	Output executable path.
`--name`	`string`	Directory name	Application display name.
`--version`	`string`	`1.0.0`	Semantic version string (`X.Y.Z`).
`--app-id`	`string`	`com.hrunner.<name>`	Unique reverse-DNS application ID.
`--python`	`string`	`3.13.7`	Required Python runtime version.
`--allow-compatible`	`bool`	`false`	Allow existing installed compatible minor runtimes.
`--entrypoint`	`string`	Auto-detected	Main Python script (`main.py`, `app.py`).
`--publisher`	`string`	`""`	Publisher name.
`--launcher-stub`	`string`	`hlauncher.exe`	Path to custom Go launcher stub binary.

For detailed usage, see docs/build-configuration.md.

Runtime Management

Hrunner maintains a central runtime store under %LOCALAPPDATA%\Hrunner\runtimes\:

Downloads official Windows x64 embeddable distributions from python.org.
Verifies download integrity before extraction.
Isolates sys.path so the runtime cannot leak into or read from %APPDATA%\Python\site-packages.
Multiple Python versions (e.g. python-3.12.8 and python-3.13.7) coexist seamlessly.

For details, see docs/runtime-management.md.

Package Management

All third-party packages are installed into %LOCALAPPDATA%\Hrunner\packages\<name>\<version>\:

Physical Deduplication: If multiple applications require requests == 2.32.5, it is physically stored only once.
Native C-Extensions Supported: Automatically selects and extracts Windows x64 binary wheels containing compiled .pyd and .dll extensions (numpy, pillow, cryptography, opencv-python).
Checksum Verification: Every wheel is checked against SHA-256 digests from PyPI.

For details, see docs/package-management.md.

Application Isolation

Applications share packages physically on disk, but execute in total logical isolation:

App A (numpy == 1.26.4) and App B (numpy == 2.3.2) run without version bleed.
The launcher injects only the packages declared in the application's manifest into sys.path.
Native DLL search paths are configured via os.add_dll_directory().

For details, see docs/isolation.md.

Manifest Format

Every executable embeds a versioned manifest.json (format_version: 1):

{
  "format_version": 1,
  "application_id": "com.example.myapp",
  "name": "My Application",
  "version": "1.0.0",
  "publisher": "Example Corp",
  "python": {
    "version": "3.13.7",
    "allow_compatible": false
  },
  "dependencies": {
    "requests": "2.32.5",
    "pillow": "11.3.0"
  },
  "entrypoint": "main.py"
}

For details, see docs/manifest.md.

CLI Reference

`hrunner`

The main Hrunner service, management UI, and diagnostic CLI.

hrunner apps                  # List all registered applications
hrunner runtimes              # List installed Python runtime distributions
hrunner packages              # List shared package pool with reference counts
hrunner clean                 # Safely delete orphaned packages with refcount == 0
hrunner storage               # Display disk space breakdown
hrunner remove <app_id>       # Unregister an application (--clean-unused to delete orphaned packages)
hrunner --manager             # Open the native Windows Manager GUI
hrunner --pipe-server         # Start on-demand Named Pipe IPC server

`hmanager`

Direct shortcut executable to launch the native Hrunner Manager GUI.

hmanager

`hbuild`

Developer CLI for building application executables.

hbuild build <project_path> [flags]

Hrunner Manager

Hrunner includes a 100% native Windows 11 Fluent Design desktop manager (hmanager or hrunner --manager), styled after Windows 11 Settings and Lossless Scaling with zero web views or localhost networking:

Key Features

Windows 11 Fluent / WinUI 3 Aesthetics: Native DWM Mica backdrop (DWMWA_SYSTEMBACKDROP_TYPE), rounded cards (DWMWA_WINDOW_CORNER_PREFERENCE), Segoe UI Variable subpixel typography, and custom vector icons.
Home Dashboard: Real-time metric cards for registered applications, embeddable Python runtimes, shared deduplicated packages, and total storage footprint.
Applications: Inspect isolated application manifests, launch registered apps directly, or cleanly unregister them with automatic dependency impact calculation.
Python Runtimes: View centrally installed embeddable Python distributions, versions, disk paths, and installation status.
Shared Package Pool: Inspect deduplicated Python wheels with per-package application reference counts and disk sizes.
Storage & Cache: Interactive segmented disk usage visualizer breaking down runtimes, packages, application payloads, and download cache, with one-click cleanup for orphaned dependencies.
Settings & Diagnostics: Inspect central paths, IPC named pipe health, DWM backdrop status, and runtime integrity.
100% Native: Built using native Win32 + GDI+ double-buffered rendering. Zero Chromium, zero Electron, zero WebView2, zero browser windows, zero localhost HTTP ports.

Troubleshooting

See docs/troubleshooting.md for solutions to common issues:

Application reports "Hrunner is required"
Named Pipe timeouts or connection issues
Dependency conflict resolution
Resolving .pyd native extension DLL errors

FAQ

See docs/faq.md for answers to frequently asked questions about security, performance, licensing, and comparisons with PyInstaller.

Development & Testing

Run all automated unit and integration tests:

go test -v ./...

Run specific test packages:

go test -v ./pkg/manifest       # Manifest parsing & validation
go test -v ./pkg/packages       # Wheel matching & store deduplication
go test -v ./pkg/protocol       # Named Pipe IPC & auto-shutdown
go test -v ./pkg/registry       # Registry state machine
go test -v ./pkg/resolver       # Dependency resolution & conflicts
go test -v ./pkg/runtime        # Python runtime manager
go test -v ./pkg/storage        # Storage metrics & cleanup
go test -v ./pkg/ui             # Native Windows UI
go test -v ./pkg/builder        # Project packaging
go test -v ./test/integration   # End-to-end multi-app integration flow

To compile release artifacts and the NSIS installer:

powershell -ExecutionPolicy Bypass -File packaging\build_dist.ps1

Contributing

We welcome contributions! Please review CONTRIBUTING.md and our Code of Conduct before submitting pull requests.

Security

Please report security issues responsibly. See SECURITY.md for details on our reporting process and supported versions.

Roadmap

See docs/roadmap.md for our feature roadmap and planned capabilities.

License

Hrunner is licensed under the GNU General Public License v3.0 (GPL-3.0).

Name		Name	Last commit message	Last commit date
.github		.github
cmd		cmd
docs		docs
examples		examples
packaging		packaging
pkg		pkg
test		test
tests/benchmarks		tests/benchmarks
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
SUPPORT.md		SUPPORT.md
go.mod		go.mod
go.sum		go.sum
walkthrough.md		walkthrough.md

Latest commit

History

Folders and files

Repository files navigation

Hrunner

Table of Contents

Overview

Why Hrunner?

Comparison

Architecture

How It Works

Developer Machine

End User Machine

Installation

For End Users

For Developers (Building from Source)

Quick Start

1. Create a Python Project

2. Build the Application

3. Run the Executable

Build Parameters

Runtime Management

Package Management

Application Isolation

Manifest Format

CLI Reference

hrunner

hmanager

hbuild

Hrunner Manager

Key Features

Troubleshooting

FAQ

Development & Testing

Contributing

Security

Roadmap

License

About

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

`hrunner`

`hmanager`

`hbuild`