Warning

This documentation is actively being updated as the project evolves and may not be complete in all areas.

Packages

Python

Jumpstarter includes the following installable Python packages:

  • jumpstarter: Core package for exporter interaction and service hosting

  • jumpstarter-cli: CLI components metapackage including admin and user interfaces

  • jumpstarter-cli-admin: Admin CLI for controller management and lease control

  • jumpstarter-driver-*: Drivers for device connectivity

  • jumpstarter-imagehash: Image checking library for video inputs

  • jumpstarter-testing: Tools for Jumpstarter-powered pytest integration

Installing Packages

The Jumpstarter Python packages provide all the tools you need to interact with hardware locally.

Prerequisites

  • Python >=3.11

  • A package manager such as pip or uv.

To install all the Jumpstarter core packages and drivers, use the jumpstarter-all meta package:

Tip

Consider installing your Python packages in a virtual environment instead of globally.

# Install with pip
$ pip3 install --extra-index-url https://pkg.jumpstarter.dev/simple jumpstarter-all

# Create config directories for Jumpstarter
$ mkdir -p "${HOME}/.config/jumpstarter/"

# Create the exporter config directory
$ sudo mkdir /etc/jumpstarter

# Create a new virtual environment
$ python3 -m venv ~/.venv/jumpstarter
$ source ~/.venv/jumpstarter/bin/activate

# Install with pip
$ pip3 install --extra-index-url https://pkg.jumpstarter.dev/simple jumpstarter-all

# Create config directories for Jumpstarter
$ mkdir -p "${HOME}/.config/jumpstarter/"

# Create the exporter config directory
$ sudo mkdir /etc/jumpstarter

# Create a new virtual environment
$ uv venv

# Install with uv
$ uv add --extra-index-url https://pkg.jumpstarter.dev/simple jumpstarter-all

# Create config directories for Jumpstarter
$ mkdir -p "${HOME}/.config/jumpstarter/"

# Create the exporter config directory
$ sudo mkdir /etc/jumpstarter

Additional package indexes are available, this is a complete list of our indexes:

Index

Description

releases

Release, or release-candidate versions

main

Index tracking the main branch, equivalent to installing from sources

release-0.6

Index tracking a stable branch

Installing from Source

Jumpstarter is in active development with frequent feature additions. We conduct thorough testing and recommend installing the latest version from the main branch.

Prerequisites

  • uv - A modern Python package manager for monorepos.

  • make - The make build tool.

  • git - Clone the repository with Git.

Run the following commands to clone the repository and create a virtual environment:

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

# Open Jumpstarter
jumpstarter$ cd jumpstarter

# Install Python venv and sync packages with uv
jumpstarter$ make sync

# Create local config directories for Jumpstarter
$ mkdir -p "${HOME}/.config/jumpstarter/"

# Create the exporter config directory
$ sudo mkdir /etc/jumpstarter

# Activate the virtual environment to use the Jumpstarter CLI
$ source .venv/bin/activate
$ jmp version

Run in a Container

If you prefer not to install packages locally, you can run Jumpstarter from a container using Docker or Podman.

First, create the config directories so you can mount them inside the container:

# Create local config directories for Jumpstarter
$ mkdir -p "${HOME}/.config/jumpstarter/"

# Create the exporter config directory
$ sudo mkdir /etc/jumpstarter

To start a Jumpstarter container with all the driver packages pre-installed, run:

$ podman run --rm -it \
    -v "${HOME}/.config/jumpstarter/:/root/.config/jumpstarter":z \
    quay.io/jumpstarter-dev/jumpstarter:latest jmp

$ docker run --rm -it \
    -v "${HOME}/.config/jumpstarter/:/root/.config/jumpstarter":z \
    quay.io/jumpstarter-dev/jumpstarter:latest jmp

To interact with Jumpstarter without local Python package installation, create an alias to run the jmp client in a container.

We recommend adding this alias to your shell profile (~/.bashrc or ~/.zshrc) for persistent use:

$ alias jmp='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'

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

If you’ve configured a jmp alias you can undefine it with:

$ unalias jmp

When you need hardware access for running the jmp command or following the local-only workflow, configure the container with device access, host networking, and privileged mode. This typically requires root privileges:

$ sudo 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

$ sudo docker 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