Hypersphere guide

Install and run

Hypersphere is built from source today: its source is not published yet, and installers for macOS, Windows and Linux are not available yet either. With a copy of the source, one developer script, tools/dev.py, sets up, builds, runs and tests every part. Each step prints the command it runs and stops at the first failure.

To try it without building anything, pick an example mission in the showcase: it opens in the hosted workstation, in your browser, as your own copy. Opening one asks for the user name and password the owner hands out.

Requirements

Build from source

From the root of the source tree:

python3 tools/dev.py setup     # npm dependencies, Electron, .venv, Playwright Chromium
python3 tools/dev.py build     # generated files, engine, WebGPU renderer, extension, workstation

setup installs the npm dependencies of the fork and of the Hypersphere extension, fetches Electron, creates .venv with the hypersphere Python package (editable, with the notebook extras) and installs Chromium for the browser tests. Add --force to reinstall the npm dependencies.

build regenerates the design tokens, JSON schemas, TypeScript engine types, command reference and Python catalogue, then builds the engine, the WebAssembly renderer, the extension and the workstation client. Add --release for an optimized engine, or --no-fork to skip the workstation client.

Run the workstation

The workstation opens a mission folder: a folder whose root holds mission.json. Without an argument, run opens the LEO operations example:

python3 tools/dev.py run                        # examples/leo-operations
python3 tools/dev.py run examples/quickstart    # any mission folder

The workstation starts the engine for the folder and opens its Scene. It keeps its own profile in .build/dev-profile, so it never touches another VS Code installation; --profile DIR chooses another one, and --inspect PORT enables Chromium remote debugging. Inside the workstation, Hypersphere: New Mission and Hypersphere: Open Example Mission in the Command Palette start a mission without a terminal.

Test your build

python3 tools/dev.py check          # formatting, lints, generated-file freshness
python3 tools/dev.py test --quick   # checks, Rust, examples, Python, design system and extension unit tests
python3 tools/dev.py test           # plus the browser, WebGPU, workbench and end-to-end suites

The workstation

The Scene fills the window, and the workstation’s panels float over it as glass cards: Objects on the left, the Overview and the Inspector on the right, Events and the Timeline below. Every view reads the same mission from the engine and shares one selection and one clock, so selecting an object or an event anywhere moves all of them.

Title bar and modes

The title bar holds four modes, which lay the workstation out for a task: Analysis (Objects, the Overview and Events around the Scene), Events, Reports and Scene, which hides the panels for an immersive view with only the Scene’s own Objects card. Switch with ⌃⌘1–⌃⌘4 on a Mac or Ctrl+Alt+1–Ctrl+Alt+4 elsewhere, or from the Command Palette. The search field (⌘K, Ctrl+K, outside text fields) finds objects, events and commands; Hypersphere: Go to Mission Item (⇧⌘;, Ctrl+Shift+;) jumps to any object, analysis, saved view, plot or report.

Objects and Views

The Mission card on the left lists the mission’s objects in their folders, its analyses with the state of each result, and below them the saved camera Views, plots and reports. A click selects a row, the eye beside it shows or hides it in the Scene, and its context menu holds its commands: Show Properties, Follow in Scene, Duplicate, Rename ID, Delete Object, and for a catalog Refresh from CelesTrak. The + button opens Add to Mission, and each folder’s context menu adds the kind of object it holds.

Scene

The Scene draws the mission in 3D: bodies with their atmosphere, clouds and night lights, orbits, catalog populations with their orbital-plane rings, ground stations, targets and regions, sensor volumes, access links and coverage overlays. Its playback bar plays and pauses the clock, changes the rate and jumps to the start; its tool cluster holds Layers, Views, Follow and immersive mode. The Scene describes navigation.

Overview and Inspector

The Overview on the right summarizes the mission: the Scene’s header (central body, frame, layers, immersive mode), the orbital population and its altitude histogram from a population analysis, the orbital plane of the selected spacecraft, the state of every analysis, the next events after the playhead, and a card per analysis with its summary metrics. Below it, Properties shows and edits the selected object or analysis; every edit is one undo step. In the Analysis mode Properties appears once you ask for it (Show Properties) and stays until the selection is cleared.

Events

Events lists every event of the mission in time order: acquisitions and losses of signal, culminations, eclipse entries and exits, apsides, nodes, close approaches and conjunctions, each with a severity. Filter by type or severity, search, show only the selected objects, or show each contact as one row. Selecting a row selects its objects and moves the clock to it; Track Primary Object follows its object in the Scene. Export Shown Events as CSV writes what the filters show.

Timeline

The Timeline lays the mission span out in lanes: one per access pair or other interval series of an analysis (coverage, for example), eclipses, mission events and maneuvers. Drag along the time axis to scrub the clock; click an interval or an event to select its objects and go to it. Zoom with ⌘/Ctrl and the wheel or a pinch; Zoom In, Zoom Out, Fit Mission and Follow Playhead are in its title bar.

Access and Results

Access lists every pass of the access analyses and summarizes each observer–target pair, with the selected pass’s geometry beside it; selecting a pass goes to its acquisition. Results shows any analysis result: its summary, intervals, events and every table, with Export Result Table as CSV, Export Intervals as CSV and Export Analysis Result as JSON. Every panel can move to an editor (Open … in Editor) or its own window (Open … in New Window).

Assistant

The Assistant is the workstation’s Chat view. ⌘I (Ctrl+I) opens it beside the Inspector. The AI assistant covers setup and use.

Keyboard shortcuts

Save, Undo and Redo apply to the mission while a Hypersphere view or the Scene has focus; elsewhere they keep their usual meaning. The Scene’s own keys are listed with its navigation.

Build a mission

A mission is one file, mission.json, in a mission folder: its name, time span, central body and kernels, objects, analyses, plots, reports and saved views. The engine is its only writer; every view, script and agent changes it through catalogue commands, so each change is validated, undoable and visible everywhere at once.

Start a mission

Open a folder, then run Hypersphere: New Mission: it asks for a name, writes mission.json and opens the Scene. Hypersphere: Open Example Mission opens one of the shipped examples instead. Epochs are always written with their time scale, such as 2026-10-14T00:00:00 UTC.

Spacecraft and propagators

Add Spacecraft starts from an orbit preset (ISS, sun-synchronous, GPS, Molniya, geostationary), Keplerian elements, a Cartesian state, pasted or imported two-line elements, or an ephemeris file in the mission folder; create_object also takes a CCSDS OMM element set. The propagator follows from the source:

Impulsive maneuvers (Δv in VNC, RIC or inertial axes) apply to Keplerian and Cartesian spacecraft; the trajectory splits into arcs at each burn. Add Walker Constellation creates a Walker delta or star pattern in one step, and Import Two-Line Elements imports a TLE file as spacecraft or as one catalog.

Stations, sensors, targets and regions

Add Ground Station places a station by geodetic latitude, longitude and height above WGS 84, with an optional elevation mask. Add Sensor attaches a field of view to a spacecraft or station, pointed along the parent’s attitude or at a target. Add Analysis Target marks a point of interest on a body, and Add Region draws an area as a polygon, a latitude–longitude box or a circle, for coverage and display.

Catalogs and CelesTrak

A catalog is a whole element-set file (TLE, OMM CSV or OMM JSON) drawn and screened as one population, propagated with SGP4. Hypersphere ships a dated snapshot of CelesTrak’s public GP groups (13 October 2026); the LEO operations example uses ten of them. Add Catalog from CelesTrak downloads a current group into the mission folder and Refresh from CelesTrak downloads a catalog again. Each download writes a new dated file with a provenance file beside it, at most once per group every two hours. It is the only command that reaches the network, and the workstation asks before each download.

Catalog members are not mission objects; to analyze one (access, lighting, ground track), promote it to a spacecraft with promote_catalog_member. Element sets more than 14 days from the mission span are flagged, and members more than 60 days away are not propagated.

Save, undo and recovery

Save Mission (⌘S) writes mission.json with the current playback state, selection and camera, so the mission reopens where you left it. Undo and Redo step through the engine’s history, whichever client made the change; an assistant answer or a Python undo_group is one step. If the workstation stops with unsaved changes, the next start offers Recover Unsaved Work or Discard Unsaved Work.

Analyses and results

New Analysis adds one of nine types. Analyses run in the engine whenever their inputs change, and a result depends only on the mission, the kernels and the analysis definition, never on playback, open views or thread count.

Maneuver targeting

A targeting analysis varies the Δv of a spacecraft’s named maneuvers until the orbit or rendezvous goals are met. New Analysis → Maneuver targeting, or Target a Maneuver… in a spacecraft’s properties, sets up the common cases on one burn (an apoapsis or periapsis altitude, circularize, an inclination) with a preview of the solved Δv. The engine solves it again whenever its inputs change and never changes a maneuver on its own: the Properties inspector shows the solution, each burn’s Δv now and solved and whether every goal is met, and Apply Solution writes it into the maneuvers as one undo step. From MCP or the assistant, solve_targeting returns a solution without changing anything and apply_targeting applies it; in Python, hs.targeting("geo-transfer") returns the solution and its apply() writes it. Only Δv components of impulsive burns are varied, not burn times or finite burns. examples/orbit-raising solves a transfer to geostationary orbit.

Results and events

A result has a status, summary metrics, interval series, events, tables and diagnostics. Tables start with et_s (TDB seconds past J2000) and utc_ms, and every column states its unit. While an analysis recomputes after a change, the views keep showing the previous result, marked as stale.

Export

From the workstation: Export Results as CSV on an analysis, Export Result Table as CSV and Export Intervals as CSV in Results, and Export Events as CSV in Events. From any client, export_results writes CSV or JSON into the mission folder (by default exports/<analysis>-<table>.csv). Exports never replace an existing file unless asked to with overwrite, and they never write outside the mission folder.

Plots and reports

New Plot saves a plot of result columns against time, optionally with shaded interval bands, and New Report a report of text, mission summary, results, plots and events sections. Both live in the mission. Export a plot with Export Plot as PNG or Export Plot Data as CSV, and a report with Export Report as HTML or Export Report as Markdown.

The Scene

Mouse, trackpad and keyboard

The camera orbits the followed object, keeping the pole up.

Follow, frames and views

The Scene follows the central body or any object: F, Follow in Scene or the Follow tool. Following a spacecraft or a station brings the camera to the view straight down from above it after you let go. The globe button in the playback bar switches between inertial axes and axes fixed to the central body. Views saves the camera, follow target and frame under a name, optionally with the epoch, and applies a saved view later; the same views are listed under Objects.

Scene mode and immersive

The Scene mode, or Toggle Immersive Mode (⌃⌘F, F11), hides the panels and gives the Scene the whole window, with its own Objects card; Esc brings the panels back. Without the backdrop, the Scene is an ordinary editor: set hypersphere.scene.backdrop to false.

Layers and quality

Layers turns the atmosphere, clouds, stars, sky map, grid, labels, orbits, ground tracks, sensors and access lines on and off, sets the lighting (Sun or flat) and exposure, and picks a coverage overlay. The hypersphere.scene.quality setting chooses auto, high, balanced or low rendering when a Scene opens.

Python

The hypersphere package sends catalogue commands to a running engine and reads mission snapshots and results. It needs only the standard library; pandas and numpy add DataFrames. The samples below run against examples/quickstart, and the site’s tests run them with the values shown.

Install

python3 tools/dev.py setup installs it into .venv. Elsewhere, from the source tree:

pip install ./python                 # client only
pip install './python[dataframe]'    # with pandas and numpy

Connect

With the workstation open on a mission, or hypersphere-engine serve --workspace FOLDER running, connect from that folder:

import hypersphere

hs = hypersphere.connect()
hs.wait()                             # until every analysis has its final result
hs.mission.name                       # 'Earth — Quickstart'
list(hs.mission.objects)              # ['quickstart-1', 'sg1s']
list(hs.mission.analyses)             # ['sg1s-contacts', 'quickstart-1-lighting', 'quickstart-1-elements']

connect() tries, in order: an explicit url and token; the HYPERSPHERE_URL and HYPERSPHERE_TOKEN environment variables; then the discovery file of the engine serving workspace (default: the current folder or its nearest ancestor), or the only running engine. hs.wait() blocks until the listed analyses (all of them by default) are final; queries such as states need the engine’s trajectories, which are ready by then. Mission snapshots do not change behind your back: read hs.mission again, or call refresh(), to see later changes.

Commands and undo groups

Every catalogue command is a keyword-only method. Queries return JSON; document commands return an Outcome with the new revision. Epochs are strings with a time scale, and hypersphere.to_epoch() builds them from timezone-aware datetime values.

state = hs.get_object_state(id="quickstart-1", epoch="2026-10-14T09:25:53 UTC")
round(state["geodetic"]["alt_km"], 1) # 563.4
look = hs.compute_geometry(observer="sg1s", target="quickstart-1", epoch="2026-10-14T09:25:53 UTC")
round(look["elevation_deg"], 2)       # 28.91
look["line_of_sight"]                 # True

with hs.undo_group("Add Kiruna"):     # one undo step for everything inside
    hs.create_object(object={
        "kind": "ground_station", "id": "kir-1", "name": "Kiruna KIR-1",
        "location": {"lat_deg": 67.857, "lon_deg": 20.964, "alt_km": 0.402}})
    hs.update_analysis(id="sg1s-contacts", patch={"observers": ["sg1s", "kir-1"]})
hs.results("sg1s-contacts").wait().summary["passes"]   # 23.0
hs.undo()                             # both changes at once

Engine failures raise hypersphere.EngineError subclasses such as ValidationError and NotFoundError, with the diagnostics and JSON pointers the engine reported.

Results and DataFrames

contacts = hs.results("sg1s-contacts").wait()      # blocks until the result is final
contacts.summary["passes"]                          # 13.0
contacts.summary.units["total_duration_s"]          # 's'
passes = contacts.intervals.to_dataframe()          # a row per pass: start, stop, duration_s, max_elevation_deg, …
aer = contacts.table("aer:sg1s:quickstart-1").to_dataframe()   # indexed by UTC
list(aer.columns)                                   # ['et_s', 'azimuth_deg', 'elevation_deg', 'range_km', 'range_rate_km_s']
hs.export_results(analysis="sg1s-contacts", format="csv")["paths"]
# ['exports/sg1s-contacts-aer-sg1s-quickstart-1.csv']

to_dataframe() indexes tables by utc as datetime64[ns, UTC] and keeps et_s as a column; df.attrs["units"] holds the units. table.to_csv(path) writes the engine’s own CSV.

Notebooks in the workstation

Hypersphere: New Mission Notebook opens a notebook whose kernel is already connected: hs is ready in the first cell, tables display as tables and matplotlib figures inline. Open Results in Notebook starts one from an analysis. The kernel runs in a Python environment the workstation manages, with the hypersphere package, IPython, numpy, pandas and matplotlib; Set Up Python Environment builds it again, and Select Python Interpreter or hypersphere.python.interpreterPath picks the Python (3.10 or newer) it is built from.

MCP and external agents

hypersphere-engine mcp gives MCP clients such as Claude Code and Claude Desktop the whole catalogue as tools: one tool per command, with the same names, schemas and descriptions the workstation and Python use. Queries are marked read-only, commands that discard work are marked destructive, and fetch_gp_group, the one command that reaches the network, is marked as such. When an engine is already serving the folder (the workstation’s), every call goes to it, so an agent’s changes appear live and undo like your own.

Claude Code

claude mcp add hypersphere -- /path/to/hypersphere-engine mcp --workspace /path/to/mission
claude mcp list                     # hypersphere should report Connected

Add --scope project before the server name (options after -- go to the engine) to share the server with everyone who works in the folder; Claude Code then writes .mcp.json at the project root and asks each user to approve it once. Inside a session, /mcp shows its status and tools.

Claude Desktop

Open Settings → Developer → Edit Config, add the entry under mcpServers with absolute paths, then quit and restart Claude Desktop:

{
  "mcpServers": {
    "hypersphere": {
      "command": "/path/to/hypersphere-engine",
      "args": ["mcp", "--workspace", "/path/to/mission"]
    }
  }
}

If the server does not appear, run the same command in a terminal to see its error.

Things to ask

• “List the objects in the mission and describe the orbit of Quickstart-1.”
• “Add a ground station at Kiruna, 67.857° N, 20.964° E, with a 5° elevation mask, and add it to the contacts analysis.”
• “What are the azimuth, elevation and range of Quickstart-1 from Svalbard at 09:25:53 UTC?”
• “Create a Walker constellation of 24 satellites in 3 planes at 1,000 km and 55°.”
• “Export the contact table as CSV.”

The AI assistant

The assistant is the workstation’s Chat view, answering with Claude. Its tools are the catalogue commands, generated from the same schemas as the GUI, Python and MCP, plus a few workstation actions (open a view, plot or report, start a notebook, switch mode). The Chat view shows each call it makes.

Set up your API key

The hosted workstation that opens from the showcase needs no key: its assistant runs on the server’s own access. A workstation you run yourself uses your own Anthropic API key. Run Assistant: Manage Anthropic API Key, or open Manage Language Models, choose Anthropic and enter the key; create one in the Claude Console. The key is kept in the system’s secret storage, never in settings, logs, the mission or the chat. A server or headless run reads ANTHROPIC_API_KEY, or a key file named by HYPERSPHERE_ANTHROPIC_KEY_FILE that only you can read (chmod 600). Without a key, the assistant answers with these steps and sends nothing.

Ask and Agent

Pick the mode under the input. Ask reads the mission and never changes it: it has only the read-only tools, and no exports. Agent builds and edits the mission. The model picker offers Claude Haiku 5.5 (the default), Sonnet 5.5 and Opus 5.5 (the hosted workstation offers Haiku and Sonnet, through the server's own access), each with a thinking-effort option, and the tool picker limits which Hypersphere tools a request may use.

What it can do

Anything the catalogue can: create and edit objects and analyses, read results and events, compute states and geometry, build plots and reports, export files and move the clock, the selection and the camera. Assistant: Ask About Selection starts a question about what is selected.

Confirmations and undo

Destructive commands, and exports that would replace a file, wait for your confirmation in the chat; the permission picker under the input can approve them automatically. Everything one answer changes is one undo step, and Undo These Changes beside the answer reverts exactly that step while nothing newer has changed the mission.

The engine command line

hypersphere-engine is the engine. The workstation starts it for you; run it yourself to serve a mission, validate one in CI, or export a scene or an ephemeris. After python3 tools/dev.py build it is target/debug/hypersphere-engine (target/release/ with --release), and cargo run -p hypersphere-engine -- <command> builds and runs it in one step.

MISSION is a mission file or a folder that holds mission.json. Built-in data (kernels, textures, the star catalogue, the catalog snapshot) is found next to the executable or in the nearest data/ folder above it; --data-dir chooses another.

serve

target/debug/hypersphere-engine serve --workspace examples/quickstart
{"hypersphere":"ready","instance":"01M4XBTWBVVDBYSACPMKN1B0QB","pid":13706,"port":50410,"protocol":1,"version":"0.2.0"}

The engine listens only on 127.0.0.1 (--port 0, the default, picks a free port) and prints exactly one ready line. Every request needs the session token: it comes from HYPERSPHERE_TOKEN, or is generated and written only to a discovery file in your per-user state folder, which the Python client and hypersphere-engine mcp read. The engine never prints the token, and it stops on end of input, Ctrl-C, SIGTERM or when the process given with --parent-pid exits. One engine owns a mission at a time. GET /health needs no token.

check, run and export-scene

target/debug/hypersphere-engine check examples/quickstart
examples/quickstart/mission.json: Earth — Quickstart
  info [j2_mean_elements] at /objects/0/orbit: j2: Brouwer mean elements given; mean a = 6928.137 km, …
  info [earth_orientation_quality]: Earth orientation itrf93: short-term predict 2026-10-14T00:00:00.000Z … 2026-10-15T00:00:00.000Z …
  7 products (0 failed), 3 tracks, 7 kernels, 2106 ms
valid

They exit with 0 when the mission is valid, 1 when any diagnostic is an error, and 2 when the mission cannot be read or the outputs cannot be written. --json prints the full report: diagnostics, products, and the kernels used with their SHA-256. They take no lock, so they run while the workstation has the same mission open.

Data and validation

Kernels, frames and time

Frames, ephemerides, orientation and time come from ANISE with JPL kernels: the DE440s planetary ephemeris, and Earth orientation in ITRF93 from 1962 to 2126. Every epoch carries its time scale and every vector its frame. Outside a kernel’s coverage an analysis fails with a diagnostic that names the kernel, never a zero or a silent gap; IAU_EARTH is used only when you choose it.

The catalog snapshot

The shipped CelesTrak GP groups were retrieved on 13 October 2026 and are kept byte for byte, with their checksums; one file, the active satellites outside the other groups, is derived from CelesTrak’s active group. SGP4 errors grow by kilometres per day away from the element epoch, so the snapshot suits missions within days of that date; download current groups for later spans (Catalogs and CelesTrak).

The data manifest

data/manifest.json lists every shipped file (kernels, imagery, the star catalogue, the catalog snapshot, ground station coordinates) with its SHA-256, source and license, and the build checks every file against it. The credits on the home page are generated from it.

Validation

Each example mission ships with expected/validation.json: checks of the engine’s answers against analytic formulas, published values and independent brute-force searches, each with its provenance and a tolerance from a written error budget. python3 tools/examples/run.py runs them, and python3 tools/dev.py test runs them for every example.

Troubleshooting

The engine stopped or will not start

The title bar shows Engine Failed: Show Engine Log. Read the log with Hypersphere: Show Engine Log, fix the cause, then run Hypersphere: Restart Engine. One engine serves a mission at a time: a second engine on the same folder exits with code 3.

The Scene says WebGPU is unavailable

The Scene lists the adapter it found and the reason. Update the graphics driver; on Linux, use a GPU with Vulkan. hypersphere.scene.quality set to low lowers the load on weaker GPUs.

An analysis fails with a kernel coverage diagnostic

The mission span reaches outside the data of a kernel the analysis needs, such as Earth orientation before 1962 or after 2126. Move the span inside the coverage the diagnostic names.

Python cannot find the engine

hypersphere.connect() raises HypersphereNotRunning when no engine serves the folder. Open the mission in the workstation or start hypersphere-engine serve --workspace FOLDER, then connect from inside that folder, or pass workspace=.

The assistant asks for a key

No Anthropic API key is set up, or the key was rejected. Run Assistant: Manage Anthropic API Key and enter an Anthropic API key from the Claude Console; a malformed key is reported as soon as you enter it, and a rejected one when the assistant first answers.

Catalogs warn about stale element sets

Some element sets are more than 14 days from the mission span. Download the group again with Refresh from CelesTrak, or keep the span within days of the element epochs.