Jumpstarter

A free, open source tool for automated testing on real and virtual hardware with CI/CD integration. Simplify device automation with consistent rules across local and distributed environments.

Highlights

• 🧪 Unified Testing - One tool for local, virtual, and remote hardware
• 🐍 Python-Powered - Leverage Python's testing ecosystem
• 🔌 Hardware Abstraction - Simplify complex hardware interfaces with drivers
• 🌐 Collaborative - Share test hardware globally
• ⚙️ CI/CD Ready - Works with cloud native developer environments and pipelines
• 💻 Cross-Platform - Supports Linux and macOS

Repository Structure

This monorepo contains all Jumpstarter components:

Directory	Description
python/	Python client, CLI, drivers, and testing framework
controller/	Kubernetes controller and operator (Jumpstarter Service)
protocol/	gRPC protocol definitions (protobuf)
e2e/	End-to-end testing infrastructure

Quick Start

Install the CLI

pip install --extra-index-url https://pkg.jumpstarter.dev/ jumpstarter-cli

Or install all Python components:

pip install --extra-index-url https://pkg.jumpstarter.dev/ jumpstarter-all

Deploy the Service

To install the Jumpstarter Service in your Kubernetes cluster, see the Service Installation documentation.

Components

Python Client & Drivers (python/)

The Python implementation provides:

• jmp CLI tool for interacting with hardware
• Client libraries for test automation
• Hardware drivers for various devices
• Testing framework integration

See python/README.md for details.

Jumpstarter Service (controller/)

The Kubernetes-native service that provides:

• Centralized hardware management
• Client and exporter routing
• Authentication and authorization
• Multi-tenant support

Prerequisites:

• Kubernetes v1.11.3+
• kubectl v1.11.3+

See controller/README.md for deployment instructions.

Protocol (protocol/)

The gRPC-based communication layer that enables:

• Unified interface for virtual and physical hardware
• Secure communication over HTTPS
• Tunneling support for Unix sockets, TCP, and UDP
• Flexible topology with direct or routed connections

See protocol/README.md for details.

End-to-End Tests (e2e/)

Comprehensive testing infrastructure for the entire Jumpstarter stack:

• setup-e2e.sh - One-time environment setup (auto-installs bats libraries on macOS)
• run-e2e.sh - Quick test runner for iterations
• action.yml - GitHub Actions composite action for CI/CD
• Full integration tests covering authentication, exporters, and clients

Run e2e tests locally:

# First time setup
make e2e-setup

# Run tests (repeat as needed)
make e2e        # or: make e2e-run

# Or full setup + run in one command
make e2e-full

# Clean up e2e environment (delete cluster, certs, etc.)
make e2e-clean

Development

Prerequisites

• Python 3.11+ (for Python components)
• Go 1.22+ (for controller)
• Docker/Podman (for container builds)
• kubectl (for Kubernetes deployment)

Building

# Build all components
make all

# Build specific components
make python      # Python packages
make controller  # Controller binary
make protocol    # Generate protocol code

# Run tests
make test

# Run end-to-end tests
make e2e-setup  # First time only
make e2e        # Run tests
make e2e-clean  # Clean up

Running Locally

# Start a local development environment
make dev

Documentation

Jumpstarter's documentation is available at jumpstarter.dev.

• Getting Started
• User Guide
• API Reference
• Contributing Guide

Contributing

Jumpstarter welcomes contributors of all levels of experience! See the contributing guide to get started.

Community

• Matrix Chat
• Weekly Meeting
• Meeting Notes

License

Jumpstarter is licensed under the Apache 2.0 License (LICENSE or https://www.apache.org/licenses/LICENSE-2.0).