Configuration File

Pypen is driven by a single TOML file, project.toml, that lives at the root of the repository. It has three top-level sections:

  • [defaults] — global fallbacks shared by every [[project]].
  • [upstream] — optional auto-update from a remote git repo on startup.
  • [[project]] — one entry per worker (no upper limit).

[defaults] Section

python_version
Python version used to build per-project venvs. May be overridden per project. Default: "3.11".
dnf_packages
System packages installed once, before any project is cloned (e.g. ["ffmpeg", "aria2"]).
access_token
Default access token for cloning private repos. Each project may override this.
username / password
Login credentials for the dashboard. If either is empty, the dashboard refuses to log in.
ping
Boolean. Enable the keep-alive ping service.
ping_url
Explicit URL for the keep-alive pinger. Overrides APP_URL and any auto-detection.

[upstream] Section

repo
Git URL of the upstream tree. When non-empty, update.py hard-resets the local tree to repo@branch on every container start.
branch
Branch / tag / commit to pin to. Default: "main".

[[project]] Entries

One [[project]] table per worker. Required keys: id, git_url, branch, run_command.

id
Unique worker name. Used for the s6 service name and the log directory. Must be unique across all projects.
git_url
HTTPS clone URL of the repository.
branch
Branch, tag, or commit to check out after cloning.
repo
"public" (default) or "private". When private, the access token is injected as x-access-token:<token>@ basic-auth credentials.
access_token
Per-project access token. Falls back to [defaults].access_token.
python_version
Override the global Python version for this project.
run_command
Entry point inside the cloned repo. Either a file (e.g. "bot.py") or any shell command. Run inside the project's venv.
logs_size
Log rotation threshold. Accepts byte counts or suffixed values ("10M", "50M", "1G"). One archive is kept; older rotations are deleted. Default: "10M".

[project.env] Sub-table

Environment variables exported into the worker process. All values are coerced to strings. 

[project.env]
BOT_TOKEN = "123456:ABC-DEF"
DB_URL    = "postgres://user:pass@host/db"
LOG_LEVEL = "info"

[project.cron] Sub-table

restart_on
Restart the worker every N hours. "0" or "" disables scheduled restarts.
redeploy
Boolean string. When "true", restarts also wipe and rebuild the venv (fresh pip install).
idle
Auto-start the worker after this many minutes of idle. "0" or "" disables.
pull_commits
Boolean string. git pull before each (re)start. Default: "true".

Full Example

[defaults]
python_version = "3.11"
dnf_packages   = ["ffmpeg", "aria2"]
access_token   = ""
username       = "admin"
password       = "change-me"
ping           = true
ping_url       = ""

[upstream]
repo   = ""
branch = "main"

[[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"

[[project]]
id             = "worker02"
git_url        = "https://github.com/example/private-bot"
branch         = "production"
repo           = "private"
python_version = "3.12"
run_command    = "mybot"
logs_size      = "50M"

[project.env]
BOT_TOKEN = "123456:ABC-DEF"
DB_URL    = "postgres://user:pass@host/db"

[project.cron]
restart_on   = "6"
redeploy     = "true"
idle         = "10"
pull_commits = "true"