Hyperplane

Hyperplane is a study planning and orchestration system for running parameterized workloads against containerized services on managed node fleets. The controller is the single source of truth, agents execute container lifecycles on nodes, and the webconsole and CLI are first class clients of the controller API.

The repository includes the controller, CLI, study system, webconsole, container image definitions, and supporting docs and specs.

Architecture Overview

Key principles:

• The controller owns all operational actions and state. It is the authoritative hub for agent connections, EC2 orchestration, and container lifecycle commands.
• The webconsole is a UI proxy and never talks to agents directly. Browsers only talk to the webconsole.
• The CLI uses the controller API for the same operations exposed in the webconsole.
• Studies compile high level parameter sweeps into deterministic execution plans that the controller runs.

Reference: docs/ARCHITECTURE.md

Repository Structure

• hyperplane-controller/ — Controller server, REST API, agent hub, event stream.
• hyperplane-webconsole/ — Web UI server that proxies controller APIs.
• hyperplane-cli/ — CLI client and system orchestration commands.
• hyperplane-study/ — Study composition, planning, and execution plan generation.
• containerdefs/ — Dockerfiles and parameter models for systems under test and test clients.
• paramodel/ — Parameter modeling framework used by the study layer.
• docs/ — Architecture, node lifecycle, study system specs, and narratives.
• attic/ — Legacy or deprecated code kept for reference.

Modules and Architectural Rules

Module responsibilities:

• hyperplane-controller/: Authoritative control plane. Owns state, agent connections, EC2 orchestration, and execution of study plans.
• hyperplane-webconsole/: UI server only. Proxies controller APIs and renders state for the browser.
• hyperplane-cli/: CLI client for the same operations exposed by the controller API.
• hyperplane-study/: Study composition and planning. Compiles parameter sweeps into deterministic execution plans.
• paramodel/: Parameter modeling library used by study planning and container parameter definitions.
• containerdefs/: Docker image definitions and parameter annotations for systems and clients.

Key architectural rules:

• The controller is the single source of truth and owns all operational actions.
• The webconsole never talks directly to agents; all agent traffic goes through the controller.
• Browsers never talk directly to the controller; they only talk to the webconsole.
• CLI and webconsole capabilities are parity targets and both use controller APIs.
• The study plan is the contract: the controller executes exactly what the planner emits.

Prerequisites

• Java 25 (preview enabled via Maven configuration)
• Maven 3.8+
• Docker for image builds and container runs
• AWS credentials when provisioning EC2 constellations

Build

Build all modules:

mvn -q -DskipTests package

Running (Developer Basics)

Show CLI commands:

bin/hyperplane --help

Controller API reference: hyperplane-controller/CONTROLLER-API.md

Environment variables used by clients: docs/ENVIRONMENT.md

Study System

The study system turns parameter selections into deterministic execution plans with explicit lifecycles, concurrency, and result capture. It is specified and iterated in:

• docs/studies/study_system.md
• docs/narratives/studies/

Container Images

Container definitions live in containerdefs/ and are self bootstrapping builds with parameter annotations. See:

• containerdefs/README.md

Additional Docs

• docs/ARCHITECTURE.md — Core system rules and component responsibilities.
• docs/NODE-CONTRACT.md — Agent contract and cloud-init expectations.
• docs/NODE-LIFECYCLE.md — End to end node lifecycle and state transitions.