Skip to content

User Guide

Jump to bottom
Finnegan's Owner edited this page Jul 13, 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")
  • 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
Engine Type Integration engine vendor/type (used to key the shared JAR cache). Pick an existing value or type a new one.
Java Home Path to a JavaFX-enabled JDK. Pre-filled from the JAVA_HOME environment variable if set; otherwise leave blank to use java on PATH.
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

JavaFX is required. The administrator is a JavaFX application, so the Java used to launch it must be a JavaFX-enabled JDK. A plain OpenJDK starts and then fails with "JavaFX runtime components are missing". Launcher does not search for or guess a JDK: it uses the connection's Java Home if set, otherwise java on PATH. Before any download, it runs a quick java -version check and, if Java can't run, stops with a clear "Java (with JavaFX) not found" error.

Options

Option Description
Show console Opens a native console window that streams the administrator's stdout and stderr (see below)
Do not cache Re-downloads JARs on every launch instead of using the shared cache

Console

Enable Show console on a connection to stream the administrator's output into a native console window. The window:

  • Opens only after the administrator process spawns successfully, so a failed launch never leaves an empty console open.
  • Streams both stdout and stderr live (stderr lines are shown in red), with auto-scroll that sticks to the bottom while you are near it.
  • Has its own light/dark toggle, independent of the main window theme, plus Clear, Copy, and Save controls.
  • Closes automatically when the administrator exits cleanly (exit code 0). On a non-zero exit it stays open and shows the exit status so errors remain readable.
  • Reuses the open window when you relaunch the same connection, inserting a "relaunched" separator.

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

Integration engine servers almost always present self-signed certificates, so Launcher does not validate a certificate chain. Instead it pins each connection to a specific server certificate using trust-on-first-use (TOFU).

First connection. The first time you launch a connection, Launcher captures the server's leaf certificate and shows a Trust this server's certificate? dialog with:

  • Subject
  • Issued by
  • Expires
  • SHA-256 fingerprint (shown colon-separated, like openssl x509 -fingerprint -sha256)

Verify the fingerprint with the server operator out of band before trusting. Click Trust certificate to pin it to this connection, or Cancel to abort the launch.

Later connections. On every subsequent launch the server must present the same certificate. If it matches, the launch proceeds without prompting. If the certificate has changed, Launcher shows a red This server's certificate changed warning with both the previously trusted fingerprint and the new one. The safe choice (Cancel) is the keyboard default; choose Trust new certificate only if you expected the change (for example, the server's certificate was renewed).

The pin is stored per connection as pinnedCertSha256 in ~/.launcher/launcher-data.json. There is no separate shared certificate trust store.

Forgetting a pin. Open the connection editor and, under Security, click Forget to clear the pinned fingerprint. The next launch prompts you to trust a certificate again.

Launcher still verifies the TLS handshake signature, so the server must prove it holds the certificate's private key — a copied fingerprint alone cannot impersonate it. Hostname/SAN is intentionally not checked, because self-signed engine certs rarely carry a SAN matching the configured address; the pin is the trust boundary.

Data Storage

Launcher stores its data in ~/.launcher/:

File Purpose
launcher-data.json All connection configurations, including each connection's pinned certificate fingerprint
cache/ Downloaded JAR cache
logs/ Administrator process logs (one per connection)

On macOS and Linux, launcher-data.json is created owner-only (permissions 0600) and the ~/.launcher directory itself is 0700, since the file can hold saved passwords. Windows relies on the user profile's default access control.

JAR Caching

Launcher caches downloaded JAR files to avoid re-downloading them on every launch. The cache is keyed by engine type and server (JNLP) version, so connections to servers of the same type and version share one cache:

~/.launcher/cache/
  └── {engine-type}/
      └── {jnlp-version}/
          ├── core/
          │   ├── mirth-client.jar
          │   ├── mirth-client-core.jar
          │   └── ...
          └── extensions/

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.

Cache-collision warning. Because the cache is keyed by engine type and version, two connections that share the same engine type and version share one cache directory. A given engine release always ships the same jars, so if the server sends jars whose hashes don't match what's already cached for that type and version, the two connections are almost certainly pointing at different engines with the same engine-type label (for example, a Mirth connection left on the default "Open Integration Engine" engine type). Rather than silently overwrite the cache and mix one engine's jars into the other's classpath, Launcher stops and shows a warning naming the engine type and version and listing the jars that differ. You can Cancel and fix the engine type on one of the connections, or continue anyway to overwrite the cache for this launch.

"Do not cache" option uses an isolated per-connection directory (cache/_isolated/{connection-id}/) that is deleted and re-downloaded in full on every launch, bypassing the shared cache. 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