Embedding GaiaDesk in your product

Software vendors and IT providers can offer "click here to get help" inside their own product, backed by GaiaDesk and their Enterprise team. There is no SDK to compile and no source code involved.

The recommended path is GaiaDesk QuickSupport: a single, signed, run-without-installing support program your customers download from your link, run, and allow — nothing is installed, and nothing is left behind. If your customers already have the full GaiaDesk app installed, you can instead drive its support mode through the command line and links further down.

GaiaDesk QuickSupport (recommended)

QuickSupport is the host side of GaiaDesk only, in support mode only: it never installs a service, never stores a credential, is not reachable after the session, and wipes its temporary state on exit. It is the same signed program for everyone — your brand and your team come from the signed link, never from a modified binary.

1. Make a link

In the web app, open Team → Deployment → QuickSupport (Enterprise plan), pick an On-demand support client profile, and choose Create link. You get a short code like ABCD-1234 and a page at https://gaiadesk.net/qs/ABCD-1234.

2. Point your customers at it

• A link or button. Send them to https://gaiadesk.net/qs/ABCD-1234, which offers the right download for their computer, or drop the one-line snippet from the QuickSupport page into your own site or app:

  <script src="https://gaiadesk.net/app/qs-embed.js" data-gaiadesk-link="ABCD-1234" defer></script>

• From your own program. Bundle GaiaDesk-QuickSupport and run it, reading its --json event stream (below):

  GaiaDesk-QuickSupport.exe --team-link ABCD-1234 --json

3. A session

1. The customer runs QuickSupport. It shows your name and logo and one button, Allow remote support. Nothing is shared until they click it. (On macOS it first guides them through the one-time Screen Recording and Accessibility permissions.)

2. It shows this computer's ID and a one-time code. Your technician — who must be a member of your team — connects with them, and the customer is asked to accept that technician.

3. When the session ends, the customer can Close QuickSupport. It leaves nothing on the machine.

The --json event stream

--team-link <code> --json prints one JSON object per line, the same shape as gaiadesk-cli support start --json:

{"event":"awaiting_consent","brand":"Acme Help"}
{"id":"481902774","code":"582931","status":"waiting"}
{"event":"waiting"}
{"event":"connected","technician":null}
{"event":"ended"}

Exit codes: 0 ended, 1 failed, 2 nobody allowed it before --timeout (default 600 s), 3 the binary refused to run because it could not prove it is genuine, 4 no usable support profile.

The server is in charge

Every QuickSupport session needs a live link, an active Enterprise entitlement, and your team's QuickSupport switch on — all checked on the server when the host registers, so a tampered or stale copy gains nothing. You can revoke a link (every copy downloaded from it stops working) or switch QuickSupport off for the whole team at once from the same page, and every live session ends within seconds. Every session is listed there — the customer's computer, the technician, and when — as an audit trail.

What it does and does not protect

QuickSupport checks its own signature before it runs (Windows Authenticode, the notarized macOS signature, or an embedded signature on the Linux AppImage) and refuses, with a clear message, if it has been modified. This raises the cost of a tampered copy; it does not make one impossible. The real guarantee is the server: a cracked binary still cannot start a session without a live link, your entitlement and your team's technicians. QuickSupport does not include anti-debugging (which trips antivirus for no real gain).

The installed GaiaDesk app

The rest of this guide is for customers who run the full, installed GaiaDesk app: you ship the official signed installer together with a support-mode provisioning bundle, and drive it through the command line and links below.

What you ship

1. The official GaiaDesk installer for the platform (unmodified — do not repackage, re-sign or patch it).

2. A provisioning bundle from Team → Deployment, from a profile in On-demand support client mode. It carries your brand (name, logo, accent, support contact) and connects GaiaDesk to your team.

Install them as in Deploying GaiaDesk, or let your installer put gaiadesk-provision.json next to GaiaDesk's installer.

How a support session works

1. Your app starts a support session (below).

2. GaiaDesk shows a screen with your name and logo and one button: Allow remote support. Nothing is shared until the customer clicks it.

3. GaiaDesk then shows this computer's ID and a one-time code. Your technician connects with them; the customer is asked to accept that technician by name, and while the session lasts GaiaDesk shows that someone is connected (and who, in its session panel) with an End session button.

4. When the session ends, everyone is disconnected, the code is replaced (the one that was read out no longer works), GaiaDesk stops using the session's credential, and the customer can Close GaiaDesk or Remove it.

A support-mode bundle never installs a background service and never makes the machine reachable after the session.

Starting a session from your app

Command line

gaiadesk-cli support start --json [--profile <profile id>] [--timeout <seconds>]

It prints one JSON object per line:

{"event":"awaiting_consent"}
{"id":"481902774","code":"582931","status":"waiting"}
{"event":"waiting"}
{"event":"connected"}
{"event":"ended"}

• The line with id and code appears once, after the customer allows the session. Show them in your UI or send them to your ticketing system.

• Exit code 0 when the session ends, 1 if it failed (the last line has an error), 2 if nobody allowed it before --timeout (default 600 s), 255 if GaiaDesk is not installed.

• Without --json the same information is printed as plain text.

gaiadesk-cli lives next to GaiaDesk: C:\Program Files\GaiaDesk\gaiadesk-cli.exe, /Applications/GaiaDesk.app/Contents/MacOS/gaiadesk-cli, /usr/bin/gaiadesk-cli.

Link

gaiadesk://support/start
gaiadesk://support/start?profile=<profile id>

Opening the link shows the same support screen. A link can never start a session by itself — the customer still clicks Allow — and GaiaDesk ignores any link it does not recognise.

A bundle can also travel in a link (gaiadesk://provision?b=…). GaiaDesk checks its signature and then asks the user before applying it; a link never applies anything silently, and GaiaDesk never downloads anything a link points at.

Detecting GaiaDesk

Removing GaiaDesk

• Windows: "%ProgramFiles%\GaiaDesk\uninstall.exe" /S (administrator). The Remove button after a session starts the same uninstaller.

• macOS: delete /Applications/GaiaDesk.app. If the customer ran GaiaDesk straight from the disk image, there is nothing to remove.

• Linux: sudo apt remove gaiadesk, or delete the AppImage.

What each platform supports

• macOS: GaiaDesk runs straight from the disk image, so a support session needs no installation at all. macOS asks the customer to allow Screen Recording and Accessibility the first time.

• Windows: GaiaDesk is installed per-machine, so the customer (or your installer) needs administrator approval once. There is no "portable" GaiaDesk for Windows: it depends on WebView2 and on components that must be installed. After the session, Remove runs the normal uninstaller.

• Linux: the AppImage runs without installation; the .deb installs system-wide.

What is and is not permitted

You may: distribute the official GaiaDesk installers unmodified alongside your product; generate and ship provisioning bundles for your own Enterprise team; start, monitor and end support sessions through the command line and links above; show GaiaDesk's ID and code in your own UI; brand GaiaDesk through your bundle.

You may not: modify, repackage, re-sign or decompile GaiaDesk; remove or hide GaiaDesk's name, its tray icon, its "someone is connected" notification or its session panel; start a session without the customer's click on Allow; share a bundle with anyone outside your organisation's deployment; use GaiaDesk to access a computer without its user's knowledge.

Your use of GaiaDesk is governed by your Enterprise agreement.