Skip to content

User Guide

Jump to bottom
Finnegan's Owner edited this page Feb 28, 2026 · 7 revisions

User Guide

Main Screen

The main screen shows all your configured server connections.

Server List

Each row displays:

  • Color avatar with the server's initials
  • Server name and address
  • Status indicator: green (available), red (unavailable), yellow pulsing (checking)
  • Last connected time (relative, e.g., "5m ago")
  • Play button to launch the administrator
  • Edit button (pencil) to edit the connection

Interactions

Action Result
Single click Select the row
Double click Launch the administrator
Play button Launch the administrator
Pencil button Open connection editor

Sorting

Click the sort icon in the header bar to sort connections by:

  • Group (default)
  • Name
  • Last connected
  • Status

Sort preference persists across sessions.

Search

Type in the search field to filter connections by name, address, or group.

Zoom

Scale the entire interface with keyboard shortcuts:

  • Cmd/Ctrl + = : Zoom in
  • Cmd/Ctrl + - : Zoom out
  • Cmd/Ctrl + 0 : Reset to default

Zoom level persists across sessions (range: 50% to 200%).

Connection Editor

Fields

Field Description
Name Display name for the connection
Address Server URL, e.g., https://hostname:8443
Java Home Path to JRE/JDK installation (auto-detected on macOS)
JVM Arguments Additional JVM options passed to the administrator process
Username Login username (optional)
Password Login password (optional)
Group Organizational group (can create new groups inline)
Heap Size JVM heap size, e.g., 512m or 1g
Notes Free-text notes

Options

Option Description
Show Java Console Opens a console window showing the administrator's stdout
Do not cache Re-downloads JARs on every launch instead of caching
Verify JAR files Verifies JAR signatures before launching (recommended)

Actions

  • Cancel: Returns to the main screen. Prompts if there are unsaved changes.
  • Save / Create: Saves the connection.
  • Delete: Removes the connection (with confirmation).

Certificate Trust

When connecting to a server with an untrusted (self-signed) certificate, Launcher will prompt you to review and trust the certificate. Trusted certificates are stored locally in ~/.launcher/launcher-trusted-certs.json.

The trust dialog shows:

  • Subject
  • Issuer
  • Expiration date
  • SHA-256 fingerprint

You can Trust (saves the cert and continues) or Reject (cancels the launch).

Data Storage

Launcher stores its data in ~/.launcher/:

File Purpose
launcher-data.json All connection configurations
launcher-trusted-certs.json Trusted certificate store
cache/ Downloaded JAR cache

Migration

Launcher automatically migrates data from previous versions:

  • ~/catapult-data.json → ~/.ballista/ → ~/.launcher/

Clone this wiki locally