Clinder starts and stops BinderHub sessions from the command line or from a GitHub Actions workflow. It gives you a running Jupyter server, built from any Binder-ready repository and running in the cloud, and the URL and token to execute code on it.
For example, the following command will start a Binder session and return the URL and Token so that you can execute code within it:
clinder start https://mybinder.org/ --github-repo binder-examples/requirementsThe problem this solves¶
Many users execute notebooks in CI (e.g. GitHub Workflows) in order to deploy to public websites or Jupyter Books. However, many notebooks require computational resources or access to data that is not accessible to the CI environments. BinderHub allows you to build and execute arbitrary computational environments in the cloud, but it cannot easily be controlled from the command line. Users need a way to request and control computational resources in the cloud, and then use these resources as part of their CI build.
What Clinder does¶
Clinder asks a BinderHub to build and launch a session, streams the build logs so you can inspect them, and reports two values when the server is ready: the URL of the running Jupyter server, and the token needed to execute code on it.
Tools like MyST and Jupyter Book read these values from two environment variables to decide where to execute code:
JUPYTER_BASE_URL: the URL of the Jupyter serverJUPYTER_TOKEN: the token for that server
The GitHub Action exports both variables for the rest of the workflow automatically. The Clinder CLI lets you export these variables yourself. A documentation build in CI can therefore execute its notebooks on a BinderHub, with no environment setup in the workflow itself.
Two ways to use it¶
GitHub Action: Provision a BinderHub session inside a workflow, for example to execute a Jupyter Book or MyST site during a deploy.
Command-line tool: Start and stop BinderHub sessions from your own machine or scripts.
The live demo is a page in these docs whose outputs were computed on Binder.
Get involved¶
Clinder is currently maintained by 2i2c, with support from Project Pythia. Our intent is upstream this project and build a broader community around it.
See how to engage to ask questions, report issues, or contribute, and about the project for its history and direction.