Installing

Pypen is distributed as a Docker image and as a plain Python source tree. The Docker image is the recommended way to run it because it bundles pyenv, uv, s6-overlay and all the system packages worker projects typically need.

Running with Docker

The simplest way to try Pypen: 

$ git clone https://github.com/MysteryDemon/pypen.git
$ cd pypen
$ cp project.toml.example project.toml
$ docker build -t pypen .
$ docker run --rm -it -p 5000:5000 \
      -v $PWD/project.toml:/app/project.toml \
      pypen

The container runs start.py, which boots the supervisor, the worker manager and the dashboard. Open http://localhost:5000/ and log in with the credentials from [defaults].

Persisting state

Cloned repos, virtual environments and logs live inside the container. Mount a volume on /app (or on the project roots) if you want them to survive across container restarts.

Installing from Source

If you'd rather run Pypen directly on a Linux host:

$ git clone https://github.com/MysteryDemon/pypen.git
$ cd pypen
$ python3 -m venv .venv && source .venv/bin/activate
$ pip install -r requirements.txt
$ cp project.toml.example project.toml
$ python start.py

You will need pyenv (with several Python versions pre-installed), git, uv, and s6-overlay available on $PATH for the worker manager to do useful work. The Dockerfile is the canonical reference for the host setup.

Deploying to Heroku / Render / Fly.io

The repository ships with a heroku.yml that builds the Dockerfile as the web process. Any platform that can run a Docker image and route HTTP traffic to $PORT will work the same way: 

build:
  docker:
    web: Dockerfile

Set APP_URL (or ping_url in project.toml) to your public URL so the keep-alive pinger knows what to ping. See Keep-Alive Ping.

Creating a project.toml

Pypen is driven entirely by a single TOML file. Copy project.toml.example to project.toml and edit it. A minimal configuration with one worker looks like this: 

[defaults]
python_version = "3.11"
username       = "admin"
password       = "change-me"
ping           = true

[[project]]
id          = "worker01"
git_url     = "https://github.com/example/public-bot"
branch      = "main"
repo        = "public"
run_command = "bot.py"
logs_size   = "10M"

[project.env]
LOG_LEVEL = "info"

[project.cron]
restart_on   = "0"
redeploy     = "false"
idle         = ""
pull_commits = "true"

A complete reference for every key is on the Configuration File page.