> ## Documentation Index > Fetch the complete documentation index at: https://docs.qomicex.top/llms.txt > Use this file to discover all available pages before exploring further. # Deep link (qomicex-launcher://) ## Deep link (qomicex-launcher://) 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 | Action | URL form | Effect | Confirmation dialog needed | | :- | :- | :- | :- | | Launch instance | `qomicex-launcher://launch?target=` | Launches that instance | No | | Open page | `qomicex-launcher://open/` | Navigates to a page inside the launcher | No | | Join room | `qomicex-launcher://join?code=` | Joins a multiplayer room | Yes | | Install plugin (store) | `qomicex-launcher://install/plugin?slug=` | Installs from the plugin store | Yes (always) | | Install plugin (direct link) | `qomicex-launcher://install/plugin?url=` | Downloads a `.qplugin` and installs it | Official domains: no confirmation; others: confirmation required | | Install modpack | `qomicex-launcher://install/modpack?type=…&projectId=…&fileId=…` | Installs a modpack from Modrinth / CurseForge / FTB | Yes | > "Confirmation dialog needed" refers to a safeguard that applies **when the link is triggered from a web page**. See [Security notes](#security-notes) below. ## Syntax rules The link structure is fixed: ```text theme={null} qomicex-launcher://? ``` * **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 ```text theme={null} qomicex-launcher://launch?target=1.20.1-Forge qomicex-launcher://launch?target=%E6%88%91%E7%9A%84%E6%95%B4%E5%90%88%E5%8C%85 qomicex-launcher://launch?target=C%3A%5Cmc%5Cinst%3AMyPack ``` `target` accepts three forms, matched in the order below: | Form | Example | Matched by | When to use | | :- | :- | :- | :- | | Instance ID | `launch?target=a1b2c3d4` | Unique ID generated by the backend | Most reliable; you can see it in the address bar of the instance details page, `/instances/` | | Instance name | `launch?target=1.20.1-Forge` | Instance name | Convenient to type, but **fails when names collide** (see below) | | directory:instance name | `launch?target=C:\\mc\\inst:MyPack` | Game directory + instance name | Required whenever duplicate instance names exist | 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 ```text theme={null} qomicex-launcher://open/settings qomicex-launcher://open/resource-center qomicex-launcher://open/instances/1.20.1-Forge ``` To prevent arbitrary page injection, **only routes registered inside the launcher can be opened**: | Route | Page | | :- | :- | | `/` | Home | | `/instances` | Instance management (Instance Management) (sub-paths allowed, e.g. `/instances/`) | | `/downloads` | Download center (Download Center) | | `/accounts` | Account management (Account Management) | | `/resource-center` | Resource center (Resource Center) | | `/connect` | Multiplayer (Multiplayer) | | `/settings` | Settings (Settings) | | `/running` | Running (Running) | | `/log-analysis` | Log analysis (Log Analysis) | 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 ```text theme={null} qomicex-launcher://join?code=482913 ``` `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 ### Install from the plugin store (recommended for site authors) ```text theme={null} qomicex-launcher://install/plugin?slug=top.qomicex.weather qomicex-launcher://install/plugin?slug=top.qomicex.weather&version=0.4.0 ``` * `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**. ### Install from a direct link ```text theme={null} qomicex-launcher://install/plugin?url=https%3A%2F%2Fexample.com%2Fmy-plugin.qplugin ``` * `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 ```text theme={null} qomicex-launcher://install/modpack?type=modrinth&projectId=AABBCC&fileId=123456 qomicex-launcher://install/modpack?type=curseforge&projectId=123456&fileId=7890&name=My%20Pack ``` | Parameter | Required | Description | | :- | :- | :- | | `type` | Yes | `modrinth` (or `mr`) / `curseforge` (or `cf`) / `ftb` / `technic` | | `projectId` | Yes | The modpack project ID on the platform | | `fileId` | Required for everything except technic | The **specific file version ID** on the platform; `technic` does not need it | | `name` | No | Instance name after installation. If omitted, the modpack's official name is used | * `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 ### Clicking a link does nothing 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. ### Test links manually If you do not want to write a web page, trigger links straight from the command line (essential for troubleshooting): ```powershell Windows theme={null} Start-Process 'qomicex-launcher://open/settings' ``` ```bash Linux theme={null} xdg-open 'qomicex-launcher://open/settings' ``` ```bash macOS theme={null} open 'qomicex-launcher://open/settings' ``` 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: | Platform | Association | Notes | | :- | :- | :- | | Windows | Written to the current user registry `HKCU\\Software\\Classes\\qomicex-launcher` on first run | No administrator rights; after moving machines or reinstalling, run the launcher once again | | Linux | Writes a `.desktop` handler under `~/.local/share/applications/` and calls `xdg-mime` | Requires `xdg-mime` and `update-desktop-database` on the system | | macOS | Written to `CFBundleURLTypes` in `Info.plist` **at packaging time** | Cannot be registered at runtime, so the app **must be an installer package**; running the bare executable will not associate the protocol | ## 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 ` 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=` or `launch?target=`, 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`. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.