Skip to main content
Other programs — web pages, browser bookmarks, desktop shortcuts, scripts — can use qomicex-launcher:// links to invoke the Launcher (Launcher) directly and have it do one thing for you: launch an Instance (Instance), join a multiplayer room, install a plugin or Modpack (Modpack), or open a specific page. Typical uses:
  • A “click here to join the server” button on a resource site or in a class group chat → join a multiplayer room directly
  • “Install with QML” on a modpack page → install the modpack automatically and name it
  • “Install to QML” on a plugin author’s site → install the plugin automatically
  • Shortcuts you make yourself → launch your usual instance in one click
qomicex:// is a private protocol used internally by the launcher for frontend-backend communication (over an IPC pipe); it is not an interface for external programs. Use qomicex-launcher:// for everything external. The two do not affect each other.

Actions at a glance

“Confirmation dialog needed” refers to a safeguard that applies when the link is triggered from a web page. See Security notes below.

Syntax rules

The link structure is fixed:
  • The action name is the first segment after // and is case-insensitive (browsers convert this segment to lowercase).
  • Parameter values are case-sensitive. For example, instance names 1.20.1-Forge and 1.20.1-forge are two different names.
  • If a parameter contains /, ?, &, a space, Chinese characters, or similar, you must URL-encode it (percent-encode). For example, the instance name my modpack must be written as %6D%79%20%6D%6F%64%70%61%63%6B.
  • Links with an unrecognized action, missing required parameters, or a route outside the whitelist are silently ignored (the launcher will not bother you with an error box).

Launch an instance

target accepts three forms, matched in the order below: If you created instances with the same name under different game directories, a bare name cannot determine which one to launch — the launcher refuses outright and tells you to use directory:instance name instead of guessing. This is not pedantry: the order of the instance list changes after the launcher scans instances. If it guessed, the same link might launch A today and B tomorrow, and you would never be told.

Notes on writing directory:instance name

  • The separator is the last colon, so Windows drive letters are never cut wrong: C:\\mc\\inst:MyPack parses correctly into directory C:\\mc\\inst + instance name MyPack.
  • :, ?, &, spaces, and Chinese characters in the directory must all be URL-encoded. C:\\mc\\inst:MyPack becomes C%3A%5Cmc%5Cinst%3AMyPack.
  • Forward slashes / and backslashes \\ are equivalent, so C:/mc/inst:MyPack works too.
  • A trailing slash at the end of the directory may be omitted.
  • If the instance name itself contains a colon (theoretically possible on Linux), use the instance ID instead.
If nothing matches, you get an “instance not found” message and nothing launches. Launching behaves exactly like clicking launch in Instance management (Instance Management) (including the Java check and memory settings).

Open a page

To prevent arbitrary page injection, only routes registered inside the launcher can be opened: The routes in the table and their sub-paths are all allowed (for example, /instances/abc is valid). Paths not listed here are ignored.

Join a multiplayer room

code is the room code the host gave you (in the form U/XXXX-XXXX-XXXX-XXXX; URL-encode it). When triggered, the launcher switches to the Multiplayer (Multiplayer) page, starts joining, and shows a dialog asking you to confirm.

Install plugins

  • slug: the plugin identifier in the store (the last segment of the store page URL).
  • version: optional. If omitted, the latest version is installed.
  • Store installs include SHA256 checks + signature verification + dependency pre-checks, making this the safest path.
  • Because a slug cannot prove its origin (any web page can make one up), this always requires your confirmation.
  • url must be http / https and point to a .qplugin package.
  • Official domains (api.qomicex.top, qomicex.top, and they must be https) skip confirmation; every other source triggers a dialog showing the source hostname and the full address.
  • For other sources, after you confirm, unsigned packages are allowed (consistent with “manual upload + risk confirmation” on the settings page). Packages with invalid signatures are still rejected.
  • Download size limit: 64 MiB.
  • For security reasons, addresses pointing to intranet/local hosts (127.0.0.1, localhost, 192.168.x.x, etc.) are rejected.
  • Redirects are not followed: the download address must serve the file directly. If the server responds with a 301/302 redirect, the install fails with “the download address returned a redirect” — use the final address instead. This blocks the trick of handing out a public address that redirects to an intranet one.
  • The certificate must be valid: this is independent of “Settings → Network → Ignore SSL certificates”; this path always verifies certificates. The reason is simple: what is downloaded here is a plugin package that will be installed and run as code, so if certificate checks could be skipped, a man in the middle could swap the plugin you are installing for something else.
Use “Settings → Plugins → Install from local” to upload a .qplugin manually instead — on that path you can see exactly which file you are installing.

Install modpacks

  • projectId and fileId usually must both be provided (a project ID alone cannot determine which version to install). The exception is type=technic, which only needs projectId — do not pass fileId with it.
  • A confirmation dialog appears after triggering; once confirmed, installation runs in the background and the launcher jumps straight to the Instances (Instance Management) page, which reports Installation started. Installation progress is not shown in the Download center (Download Center).
  • For security reasons, specifying a local file path via a link is not supported.

Security notes

External deep links can be triggered by any web page; anyone can put a qomicex-launcher:// link on their site. The launcher therefore follows two rules:
  • Any action that puts code on your machine requires your confirmation by default. This covers: installing plugins, installing modpacks, and joining multiplayer rooms.
  • Only official domains may install without confirmation, and the condition is “https + hostname exactly api.qomicex.top or qomicex.top”. Lookalike domains such as evil-qomicex.top with the same suffix are not allowed.
Actions that need no confirmation (launching an instance, opening a page) do not modify any of your data. If you clicked a link from a site you know, check the source hostname and what is about to be installed in the dialog, then confirm. If you do not recognize the source, click cancel.

Troubleshooting

Check in this order:
  • Is the launcher installed? The protocol association is registered for the current user automatically the first time the launcher runs (no administrator rights needed). A machine that has never run the launcher has no association.
  • The browser blocked it. Some browsers only allow navigating to external protocols on a user click; automatic script navigation is blocked. Use a real clickable link instead.
  • Another program claimed the protocol. Check whether something else on your system registered qomicex-launcher.
  • Check the protocol spelling. It must be qomicex-launcher://, not qomicex://.
Protocol registration can be turned on or off in Settings → Network settings → System integration. If it is switched off there, the launcher will not register itself automatically after a restart either, and links will likewise “do nothing”.

A dialog asks “This request comes from xxx”

This is expected behavior, not an error: the link’s source is not on the official domain allowlist. Check the source before deciding. If you do not want to write a web page, trigger links straight from the command line (essential for troubleshooting):
Windows
Linux
macOS
On Windows you can also run start qomicex-launcher://launch?target=1.20.1-Forge directly from the Run dialog or CMD.

Platform registration

The launcher associates the protocol differently on each system, which explains some behavioral differences:

Single-instance behavior

The launcher runs only one instance at a time, so clicking a link does not spawn a pile of windows:
  • Launcher not running → it starts normally and performs the action in the link.
  • Launcher already running → the new process hands the link to the existing window and exits; the existing window is brought to the foreground and performs the action.
When started with the --debug <port> argument (used by qomicex debug and automated debugging), single-instance mode is disabled — that mode needs a new process each time to expose the debug port. Repeated starts in this mode open multiple launchers, as expected.

Limitations

  • Local file paths are not supported. So that a link cannot point at arbitrary files on disk, install/* accepts only URLs or platform project IDs.
  • Actions cannot be chained. A link does exactly one thing.
  • You cannot pass arbitrary command-line arguments to the game. Configure custom JVM arguments in the instance settings instead.
  • Unrecognized links are silently ignored without an error message (so web pages cannot probe whether the launcher is installed on your machine).

For third-party developers

If you build a resource site, a launcher integration, or distribute plugins, you can construct the links above directly — no SDK or permission application required:
  • Want “one-click launch of an instance” → use launch?target=<instance ID> or launch?target=<directory:instance name>, but instances are local to the user, so guide users to find their own instance ID (in the address bar of the details page) rather than building the name for them — users may have duplicate names, and a bare name fails to launch.
  • Want “one-click install of your plugin” → prefer listing it in the plugin store and using install/plugin?slug=… (signature verification, more trust from users).
  • Want “direct distribution without the store” → use install/plugin?url=…, but a dialog appears every time asking the user to confirm the source. Host the package at a stable https address and provide a valid signature if possible.
  • Want “one-click modpack install” → use install/modpack?type=…&projectId=…&fileId=… (for type=technic, projectId alone is enough).
For the underlying implementation and decision record, see ADR-100 in the launcher repository; the backend endpoint for direct-link installs is POST /api/plugins/install-url.