Introduction

Overview

Pypen is a small client/server system for hosting many Python programs side-by-side inside a single container or VM. You describe each program with a [[project]] entry in project.toml; Pypen does the rest:

  1. Clones the repository at a chosen branch (public or private).
  2. Resolves the requested Python version with pyenv.
  3. Builds a fresh per-project virtual environment with uv.
  4. Generates an s6-overlay service definition for it.
  5. Starts it as a supervised long-running process.
  6. Streams its log output to a live web dashboard.
  7. Restarts it on crash, on a cron schedule, or after idle.

The whole stack — supervisor, dashboard, and worker manager — runs in one image, so you can deploy it to any Docker host, Heroku, Render, Fly.io, a free-tier VPS, or a Raspberry Pi.

Features

  • Per-project Python version via pyenv (3.8–3.13 pre-installed in the official image).
  • Isolated venvs built with uv for fast, reproducible installs.
  • True process supervision using s6-overlay; crashed processes restart automatically.
  • Live log streaming over WebSockets (Socket.IO) to a built-in Quart dashboard.
  • Cron-style restarts (every N hours), idle restarts, and optional git pull before each restart.
  • Self-update from upstream: pin the running tree to a remote git ref without rebuilding the image.
  • Keep-alive ping for free-tier hosts (Render free, old Heroku-style sleep-on-idle behaviour).
  • Bounded log files with rotation per project (logs_size = "10M").

Pypen Components

app/ — the dashboard
A Quart ASGI application served by Uvicorn. Provides the web UI, the Socket.IO log feed, and the cron loop. See Web Dashboard.
worker/ — the project manager
A long-running process that reads project.toml, clones repos, builds venvs, writes s6 service files and asks s6-svc to start them. See Projects & Workers.
ping/ — the keep-alive pinger
Tiny module that periodically pings a configured URL so free-tier hosts don't spin the dyno down. See Keep-Alive Ping.
update.py — the upstream updater
Optional self-update step run at container start. If [upstream].repo is set, the local tree is hard-reset to that remote ref before the rest of Pypen starts.
start.py — the entry point
Boots update.py, then launches Uvicorn (dashboard), s6-svscan (supervisor), the worker manager and the keep-alive pinger as parallel threads.

Platform Requirements

Pypen targets Linux x86_64 / arm64 hosts. The official image is based on Fedora 45 and ships with:

  • Python 3.8, 3.9, 3.10, 3.11, 3.12, 3.13 (via pyenv)
  • git, uv, pip, build tools
  • ffmpeg, aria2, mediainfo for common bot/scraper workloads (optional — controlled by dnf_packages)
  • s6-overlay v3.2 init system

You only need a Docker-capable host to run it. No external database, message queue, or process manager is required.