Why “Koschey”

The name comes from Koschey the Deathless — a figure from Russian folklore who hid his soul inside an egg. Koschey likewise protects the soul of each package — and keeps a close eye on Python eggs. 🥚🐍

pip install koschey

Features

Koschey can act both as a transparent proxy to public Python repositories and as a secure host for proprietary packages. It provides a unified, standards-compliant and reliable internal index for engineering teams.

• Mirror and cache. Acts as a proxy to external repositories while keeping local copies of downloaded packages for reliability and auditability. Implements last-serial support for incremental sync and minimal traffic.

• Private package hosting. Supports direct upload and storage of proprietary distributions inside your organization.

• Quarantine layer. Packages mirrored from external sources are first placed in quarantine: they are downloaded and stored locally, but remain hidden from the simple API for a configured number of days. This allows time for automated checks or manual review. Individual versions can be approved explicitly, or entire projects can be marked as trusted to skip quarantine.

• Administrative panel. Provides a web interface with multiple permission levels and flexible ACL integration. Custom authentication or access control can be added through a Python extension.

• Configurable networking. Outgoing traffic for mirrors can be routed through custom proxy logic, also extendable via Python.

• Standards compliance. Implements key packaging standards: PEP 658 (wheel metadata), PEP 691 (JSON Simple API), and PEP 710 (provenance records).

• Simple API. Provides both the classic simple (HTML/XML) interface and JSON endpoints, compatible with pip, uv and other tooling.

• High traversal efficiency. Optimized to walk and synchronize large package sets with minimal latency and bandwidth usage.

Architecture

Koschey is built with reliability and transparency in mind. It uses PostgreSQL as the primary database for package metadata, state tracking, and audit logs, and an S3-compatible object storage for package files and signatures. The system consists of several independent components — API, Worker, and Admin Panel — communicating through shared storage and the database.

Requirements

• Python >= 3.12

• POSIX-compatible system

License

Apache License 2.0 — see the LICENSE file for details.

Project links

• PyPI: https://pypi.org/project/koschey/

• Source: https://github.com/alvassin/koschey

• Issues: https://github.com/alvassin/koschey/issues