Python Packages and CLI¶

Release install¶

The Jumpstarter Python packages contain all the necessary tools to run an exporter or interact with your hardware as a client.

The Python package can be installed using pip or similar, Python >=3.11 is required.:

$ pip3 install --extra-index-url https://docs.jumpstarter.dev/packages/simple \
                                jumpstarter-all

$ mkdir -p "${HOME}/.config/jumpstarter/"
$ sudo mkdir /etc/jumpstarter

Tip

This will install the jumpstarter packages globally, when using Jumpstarter as a library, it is recommended to install the package in a virtual environment instead. i.e.

$ python3 -m venv ~/.venv/jumpstarter

$ source ~/.venv/jumpstarter/bin/activate

$ pip3 install ….

An alternative to installing the packages is to use the container package.

Development install¶

Jumpstarter is under heavy development, and new features are added frequently, we perform basic e2e testing and thorough unit testing, so we recommend installing the latest version from the main branch.

For this you will need a few tools like uv, make and git.

$ sudo dnf install -y uv make git

# Clone the repository
$ git clone https://github.com/jumpstarter-dev/jumpstarter.git
$ cd jumpstarter

$ rm .python-version # remove the python version pining

$ make # creates the dist directory with all the packages
$ make sync # installs the packages in a local .venv

# create the configuration directories
$ mkdir -p "${HOME}/.config/jumpstarter/"
$ sudo mkdir /etc/jumpstarter

Then you can use the jumpstarter cli commands by activating the Python virtual environment:

$ source .venv/bin/activate
$ jmp version

Tip

If you configured a jmp / jmp-exporter or jmp-client alias to use the container please undefine those aliases before running the jmp command.

i.e. unalias jmp

Running in a Container¶

For interacting with the Jumpstarter service without installing the Python packages locally, you can create an alias to run the jmp client in a container.

Tip

It is recommended to add the alias to your shell profile.

$ alias jmp-client='podman run --rm -it -w /home \
               -v "$(pwd):/home":z \
              -v "${HOME}/.config/jumpstarter/:/root/.config/jumpstarter":z \
               quay.io/jumpstarter-dev/jumpstarter:latest jmp-client'

Then you can try:

$ jmp-client list-configs
CURRENT   NAME      ENDPOINT                         PATH
*         default   grpc.devel.jumpstarter.dev:443   /root/.config/jumpstarter/clients/default.yaml
          test      grpc.devel.jumpstarter.dev:443   /root/.config/jumpstarter/clients/test.yaml

Hardware Access for Exporters¶

If you need access to your hardware, i.e. because you are running the jmp exporter or you are following the local-only workflow (i.e. without a distributed service), you need to mount access to devices into the container, provide host network access, and run the container in privileged mode, this probably needs to be run as root.

$ mkdir -p "${HOME}/.config/jumpstarter/" /etc/jumpstarter

# you may want to add this alias to the profile
$ alias jmp-exporter='podman run --rm -it \
              -v "${HOME}/.config/jumpstarter/:/root/.config/jumpstarter":z \
              --net=host --privileged \
              -v /run/udev:/run/udev -v /dev:/dev -v /etc/jumpstarter:/etc/jumpstarter:z \
              quay.io/jumpstarter-dev/jumpstarter:latest jmp-exporter'

Python Components¶

The Jumpstarter packages which can be installed are:

Component	Description
`jumpstarter`	The core Jumpstarter Python package. This is necessary to lease and interact with the exporters, it’s also the component that runs on the exporter hosts as a service. In most cases installation is not necessary and can be consumed through another package such as `jumpstarter-cli`.
`jumpstarter-cli`	A metapackage containing all of the Jumpstarter CLI components including the cluster admin CLI `jumpstarter-cli-admin`, the client CLI `jumpstarter-cli-client`, and exporter CLI `jumpstarter-cli-exporter`.
`jumpstarter-cli-admin`	The Jumpstarter admin CLI (`jmp-admin`). This CLI can be used to install the Jumpstarter controller, manage client/exporter registrations, and monitor/control leases.
`jumpstarter-cli-client`	The Jumpstarter client CLI (`jmp-client`/`j`). This CLI can be used to manage local client configs, start a lease on an exporter, and enter an interactive client shell.
`jumpstarter-driver-*`	All community and official driver packages that are distributed as part of Jumpstarter are prefixed with `jumpstarter-driver-*`. This includes drivers for PySerial, SD Wire, HTTP, CAN, and more. Driver packages only need to be installed on the exporter/client if they are used by your testing environment. All drivers are optional.
`jumpstarter-adapter-*`	All community and official adapter packages that are distributed as part of Jumpstarter are prefixed with `jumpstarter-adapter-*`. This includes adapters to redirect streams to local ports, unix sockets, perform ssh connections, etc.
`jumpstarter-imagehash`	A library to perform image checking from video inputs using the simple python imagehash library
`jumpstarter-testing`	Testing tools for writing Jumpstarter-powered tests with `pytest`.