Skip to content

cslcmgr

CodeSpace LifeCycle Manager: a tool that can be used to start and stop GitHub Codespaces using a GitHub PAT (Personal Access Token).

This can be used in two ways:

  • app.py: Web API server (with optional Web UI frontend), meant to be run locally on your PC, or behind a reverse proxy with authentication
  • main.py: CLI application

Usage

Important: this has been tested with Python 3.13.5 on Debian 13 (trixie).

First of all you need to generate one or more GitHub PATs (Personal Access Tokens) to be able to control your Codespaces using the GitHub API. The tokens must have the following permissions:

  • "Codespaces" repository permissions (read)
  • "Codespaces lifecycle admin" repository permissions (write)

Note: for more information on why these permissions are needed, see https://docs.github.com/en/rest/codespaces/codespaces?apiVersion=2026-03-10

Set up a Python venv (virtual environment) and install some packages inside it:

Bash
1
2
python3 -mvenv .venv
.venv/bin/python3 -mpip install -r requirements.txt

Then set the necessary configuration environment variables. Example:

Bash
1
2
3
4
export CSLCMGR_UI=true \
    CSLCMGR_IDS=mycs01,mycs02 \
    CSLCMGR_NAMES=happy-ananas-a1b2c3d4,yellow-wrench-a1b2c3d4 \
    CSLCMGR_TOKENS=github_pat_XXXXX,github_pat_XXXXX

Note: for more details about the supported environment variables, see code in the lib/config.py file.

Then you can run the web app either in a development or production configuration.

Development:

Bash
1
CSLCMGR_LOG_LEVEL=DEBUG .venv/bin/python3 app.py

Production:

Bash
1
.venv/bin/python3 -mgunicorn --access-logfile=- -w4 -b127.0.0.1:8000 'app:create_app()'

Note: for more information about running a Flask application with Gunicorn, see https://flask.palletsprojects.com/en/stable/deploying/gunicorn/

If you want to use the CLI app instead, please refer to its help message:

Bash
1
python3 main.py --help