Overview

Relevant source files

This document provides a high-level introduction to Jumpstarter, explaining its purpose as a distributed hardware testing framework, the problems it solves, its architectural components, and how these components work together. For detailed information about specific subsystems, refer to the linked pages throughout this document.

Purpose and Scope

Jumpstarter is an open-source distributed hardware testing framework designed to automate testing on both physical and virtual devices. It bridges the gap between local development workflows and production hardware environments by providing a unified abstraction layer over hardware interfaces. The system consists of Python client libraries and CLI tools, a Go-based Kubernetes controller for resource management, and Python-based exporters that interface directly with hardware.

This overview covers the system's architecture, core components, operating modes, and technology stack. For installation instructions, see Installation. For deeper technical details about specific components, see Architecture.

Sources: python/README.md1-71 python/docs/source/index.md1-62 python/docs/source/introduction/index.md1-200

What is Jumpstarter

Jumpstarter democratizes hardware-in-the-loop (HiL) testing by providing enterprise-grade testing capabilities as free, open-source software. While industries like automotive and manufacturing have traditionally used expensive proprietary HiL systems, Jumpstarter makes this technology accessible through a cloud-native approach.

The framework enables:

Local Development: Direct control of devices connected to a developer's machine
Distributed Testing: Multi-user access to shared hardware resources through a Kubernetes-based controller
CI/CD Integration: Automated hardware testing in continuous integration pipelines
Remote Access: Virtual KVM-like functionality for remote device interaction

Jumpstarter works with existing testing tools including pytest, shell scripts, Makefiles, and standard CI/CD systems, requiring minimal changes to existing workflows.

Sources: python/docs/source/introduction/index.md1-23 python/README.md18-31

System Architecture

Jumpstarter's architecture consists of three distinct layers that communicate via gRPC and are coordinated through Kubernetes custom resources in distributed mode.

Three-Layer Architecture

Sources: Diagram concepts from provided Diagram 1, python/docs/source/introduction/index.md24-48

Communication Protocols

All inter-component communication uses gRPC with Protocol Buffer message definitions located in the pkg/api directory. The protocol layer defines four primary service interfaces:

Service	Purpose	Port	Implementation
`ControllerService`	Registration, authentication, lease management	8082	pkg/controller
`RouterService`	Bidirectional stream proxying between clients and exporters	8083	pkg/router
`ClientService`	Client-side interface for exporter connections	N/A	packages/jumpstarter/jumpstarter/client
`ExporterService`	Exporter-side interface exposing driver capabilities	N/A	packages/jumpstarter/jumpstarter/exporter

Authentication flows through JWT tokens issued by the OIDC service on port 8085. The RouterService matches client and exporter streams using JWT subject claims to establish secure bidirectional communication channels.

Sources: Diagram concepts from provided Diagram 1, python/docs/source/introduction/index.md10-16

Core Components

The following table summarizes the key components in the Jumpstarter system:

Component	Type	Location	Purpose
Device Under Test (DUT)	Hardware/Virtual	N/A	Target device being tested or controlled
Driver	Python Package	packages/jumpstarter-driver-*	Abstracts hardware interfaces (power, serial, storage, etc.)
Adapter	Python Class	packages/jumpstarter/jumpstarter/adapter	Transforms driver connections into specialized formats
Exporter	Python Service	packages/jumpstarter/jumpstarter/exporter	Exposes drivers over gRPC, manages hardware lifecycle
Client	Python Library/CLI	packages/jumpstarter packages/jumpstarter-cli	Connects to exporters, manages leases, executes tests
Controller	Go Service	pkg/controller	Manages resources, enforces policies, issues tokens
Router	Go Service	pkg/router	Proxies connections between clients and exporters
Operator	Go Service	operator	Manages controller deployment and lifecycle

Sources: python/docs/source/introduction/index.md24-48

Component Interaction Flow

Sources: Diagram concepts from provided Diagram 2, python/docs/source/introduction/index.md35-48

Operating Modes

Jumpstarter supports two operating modes: local and distributed. The mode is determined by the presence of client configuration. For detailed information about operating modes, see Operating Modes.

Local Mode

In local mode, the client communicates directly with an exporter process running on the same machine via Unix socket. No Kubernetes infrastructure is required. The client library automatically spawns an exporter subprocess when using the jmp shell --exporter command.

Typical workflow:

Sources: python/docs/source/introduction/index.md56-102

Distributed Mode

In distributed mode, the system uses a Kubernetes controller to manage multi-user access to shared hardware. Clients authenticate via OIDC, acquire leases on exporters, and communicate through the RouterService. The LeaseReconciler implements sophisticated matching logic using label selectors and ExporterAccessPolicy resources.

Typical workflow:

Sources: python/docs/source/introduction/index.md104-191

Mode Selection

The operating mode is determined automatically based on configuration:

Condition	Mode	Connection Method
No client config or `JMP_CLIENT_CONFIG`	Local	Unix socket to subprocess exporter
Client config present	Distributed	gRPC to controller, proxied through router

Sources: python/docs/source/introduction/index.md56-102

Technology Stack

Client-Side Technologies

Technology	Purpose	Location
Python 3.10+	Primary language for client libraries and exporters	packages/
gRPC/Protobuf	RPC protocol for all communication	pkg/api
asyncio	Asynchronous I/O for concurrent operations	Throughout client code
Click	CLI framework for `jmp` command	packages/jumpstarter-cli
uv	Python package manager and build tool	pyproject.toml

Server-Side Technologies

Technology	Purpose	Location
Go 1.21+	Primary language for controller and operator	pkg/ operator/
Kubernetes	Orchestration platform for distributed mode	N/A
controller-runtime	Framework for building Kubernetes controllers	pkg/controller
kubebuilder	Tooling for CRD generation and scaffolding	N/A
gRPC	RPC protocol for controller services	pkg/api
JWT/OIDC	Authentication and authorization	pkg/oidc

Build and Development

Technology	Purpose	Location
buf	Protocol buffer code generation	buf.yaml
Makefile	Build orchestration	Makefile
Docker/Podman	Container image building	Containerfile
Helm	Kubernetes deployment	charts/
pytest	Python testing framework	packages/*/tests
BATS	End-to-end testing framework	e2e/

Sources: python/README.md33-50 repository structure

Repository Structure

The Jumpstarter repository is organized as a monorepo containing both Python and Go code:

jumpstarter/
├── packages/                    # Python monorepo (45+ packages)
│   ├── jumpstarter/            # Core client library
│   ├── jumpstarter-cli/        # jmp CLI tool
│   ├── jumpstarter-protocol/   # Generated protobuf stubs
│   ├── jumpstarter-driver-*/   # ~40 driver packages
│   └── jumpstarter-example-*/  # Example implementations
├── pkg/                        # Go controller and operator
│   ├── api/                   # Protobuf definitions
│   ├── controller/            # ControllerService implementation
│   ├── router/                # RouterService implementation
│   └── oidc/                  # OIDC service implementation
├── operator/                   # Kubernetes operator
├── charts/                     # Helm charts
├── e2e/                       # End-to-end tests (BATS)
├── pyproject.toml             # Python workspace definition
├── uv.lock                    # Python dependency lockfile (~7800 lines)
└── Makefile                   # Build orchestration

For detailed information about the repository structure, see Repository Structure.

Sources: Diagram concepts from provided Diagram 4, repository structure

Key Features

Hardware Abstraction

Drivers provide a consistent interface to diverse hardware types:

Power Control: Power cycling, voltage monitoring via jumpstarter_driver_power
Serial/Console: UART, USB serial via jumpstarter_driver_pyserial
Storage: Block device mounting, flashing via jumpstarter_driver_opendal
Network Services: HTTP, TFTP, SSH, VNC via various driver packages
Device Flashing: Automated firmware flashing via jumpstarter_driver_flashers

For information about specific drivers, see Driver System.

Sources: python/README.md26-27

Lease Management

The LeaseReconciler implements sophisticated resource allocation:

Matches exporters by label selectors (e.g., board=rpi4,model=v2)
Evaluates ExporterAccessPolicy rules to enforce access control
Filters by exporter online status and availability
Assigns leases with exclusive access guarantees
Tracks lease lifecycle (Created → Active → Releasing → Ended)

For details about lease management, see Lease Management System.

Sources: Diagram concepts from provided Diagram 2, python/docs/source/introduction/index.md104-176

Secure Multi-Tenancy

Distributed mode implements comprehensive security:

JWT Token-Based Authentication: All clients and exporters authenticate via OIDC
Policy-Based Authorization: ExporterAccessPolicy resources define which clients can access which exporters
TLS Encryption: Optional TLS for all gRPC communication
Stream Isolation: Router matches streams by JWT subject claim to prevent cross-talk
Resource Isolation: Leases provide exclusive access to prevent conflicts

For authentication details, see Authentication and Authorization.

Sources: python/docs/source/introduction/index.md158-176

Cloud-Native Design

Jumpstarter follows cloud-native principles:

Kubernetes-Native: Uses CRDs and controllers for resource management
Declarative Configuration: Resources defined as YAML manifests
Operator Pattern: Automated deployment and lifecycle management
Horizontal Scaling: Multiple router instances for load distribution
cert-manager Integration: Automated certificate provisioning

For deployment information, see Kubernetes Deployment.

Sources: Diagram concepts from provided Diagram 3, repository structure

Next Steps

To start using Jumpstarter:

Local Development: See Local Mode Quick Start to begin testing with local hardware
Distributed Setup: See Distributed Mode Setup for multi-user environments
Writing Tests: Explore driver capabilities in Driver System
CI/CD Integration: Review examples in packages/jumpstarter-example-*

For contributing to Jumpstarter, see Development Guide.

Sources: python/docs/source/index.md48-62