Skip to content

User Guide

Jump to bottom
Finnegan's Owner edited this page Mar 2, 2026 · 5 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")
  • Username (if configured)
  • Play button to launch the administrator (dimmed when server is unavailable)
  • 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 (only when server is available)
Pencil button Open connection editor

Sorting

Click the sort icon in the toolbar to sort connections by:

  • Group (default) — shows collapsible group headers
  • Name
  • Last connected
  • Status

Sort preference persists across sessions.

Collapsible Groups

When sorted by Group, each group header shows a chevron and connection count. Click the group header to collapse or expand that group. Collapsed/expanded state persists across sessions.

Search

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

Refresh

Click the refresh button (circular arrow) next to the search field to re-check connectivity status for all servers. Launcher checks connectivity once on startup; use refresh to re-check without restarting.

Import

Click the Import button to import connections from a JSON file (e.g., exported from another Launcher instance or migrated from MCAL).

  • A file picker opens filtered to .json files
  • If any imported connections have the same ID as existing ones, Launcher warns you and lists the duplicates
  • You can choose to overwrite the duplicates or cancel
  • After import, the page reloads to show the new connections

Help

Click the ? icon in the toolbar to open the Launcher wiki in your default browser. Launcher asks for confirmation before opening an external browser.

About

Click the info icon in the toolbar to see version information and credits (Kiran Ayyagari, original author; Diridium Technologies Inc., modifications).

Theme

Click the sun/moon icon in the toolbar to toggle between dark and light themes. Dark mode is the default. Your preference persists across sessions.

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

JAR Caching

Launcher caches downloaded JAR files to avoid re-downloading them on every launch. The cache is organized per connection and server version:

~/.launcher/cache/
  └── {connection-name}_{id-prefix}/
      └── {server-version}/
          ├── mirth-client.jar
          ├── mirth-client-core.jar
          └── ...

How it works:

  1. On launch, Launcher fetches the main JNLP from the server (always a fresh request)
  2. For each JAR listed, Launcher computes the SHA256 hash of the cached file and compares it to the hash in the JNLP
  3. If the hash matches, the cached JAR is used — no download needed
  4. If the hash differs or the JAR is missing, it is downloaded fresh

When a server is upgraded, the JNLP version changes, creating a new version subdirectory. JARs are downloaded fresh into the new directory.

"Do not cache" option deletes the entire cache directory for that connection on every launch, forcing a complete fresh download. Use this during development or to resolve issues with stale caches.

Migration

Launcher automatically migrates data from previous versions:

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

Clone this wiki locally