| 1 | --- |
| 2 | title: The desktop app |
| 3 | description: g1t in a window of its own, for Windows, macOS and Linux, with notifications from your system, a badge on the icon, g1t:// links, and updates that install themselves. |
| 4 | --- |
| 5 | |
| 6 | The desktop app is g1t in a window of its own. Everything in it is the |
| 7 | site, [g1t.sh](https://g1t.sh), loaded live: chat, agents, artifacts and |
| 8 | code, exactly as in a browser, so every change to g1t reaches the app the |
| 9 | moment it is deployed. What the app adds is what a browser cannot do: |
| 10 | |
| 11 | - **Notifications from your system**, for a message to you, a mention or |
| 12 | an agent finishing something, while the window is behind another. |
| 13 | - **A badge on the icon**, with what is waiting for you, and a tray icon |
| 14 | that keeps g1t running when the window is closed. |
| 15 | - **`g1t://` links**, which open a page in the app from anywhere on your |
| 16 | computer. |
| 17 | - **Updates that install themselves**, signed by g1t, in the background. |
| 18 | - **Your own g1t**, if you [run one](/guides/self-hosting/): the app points |
| 19 | at any server. |
| 20 | - **Settings of its own**: opening when you sign in to your computer, |
| 21 | what closing the window does, notifications, the badge, zoom and updates. |
| 22 | |
| 23 | Get it at [g1t.sh/download](https://g1t.sh/download), or from your account |
| 24 | menu, **Get the desktop app**. |
| 25 | |
| 26 | ## Install |
| 27 | |
| 28 | | Platform | What you get | Notes | |
| 29 | | --- | --- | --- | |
| 30 | | **Windows** 10 and 11 | An installer, `g1t-<version>-windows-x64-setup.exe` | Installs for your account alone; no administrator needed. Uses the WebView2 runtime Windows already has, and fetches it if a machine lacks it. | |
| 31 | | **macOS** 11 and later | A disk image, Apple silicon or Intel | Drag g1t to Applications. The app is not yet notarized with Apple: the first time, right-click it and choose **Open**. | |
| 32 | | **Linux** | An AppImage, a `.deb` or an `.rpm` | The AppImage runs anywhere once made executable (`chmod +x`). It needs WebKitGTK 4.1, which the packages install for you. | |
| 33 | |
| 34 | Every file's SHA-256 is in `SHA256SUMS` beside it, at |
| 35 | `https://g1t.sh/downloads/desktop/<version>/`. |
| 36 | |
| 37 | The app opens on g1t.sh's sign-in page, not the site's landing page: it |
| 38 | is for using g1t, not for reading about it. It keeps you signed in like a |
| 39 | browser does, and signing out brings you back to the sign-in page. |
| 40 | Signing in with GitHub goes to github.com and comes back inside the |
| 41 | window. |
| 42 | |
| 43 | ## Notifications and the badge |
| 44 | |
| 45 | Inside the app, the **Desktop notifications** switch in |
| 46 | [Settings → Notifications](/guides/notifications/#settings) is on and the |
| 47 | app shows them itself: while the window is behind another or hidden, a |
| 48 | message to you shows as a notification from your system, under the same |
| 49 | rules as in a browser: [what you chose to be told about](/guides/chat/#notifications), |
| 50 | never while [Do not disturb](/guides/chat/#sounds-and-do-not-disturb) is |
| 51 | on, never for a muted conversation. With the window in front, the pop-up |
| 52 | in the corner shows instead, as on the site. Clicking a notification |
| 53 | brings the app forward; opening the conversation it is about from the |
| 54 | notification is coming. |
| 55 | |
| 56 | The icon carries a badge with what is waiting for you: the count on macOS |
| 57 | and Linux, a lavender dot on Windows. The tray icon's hover text says the |
| 58 | number everywhere. With a notification, the taskbar icon flashes on |
| 59 | Windows and the dock icon bounces on macOS, while the window is not in |
| 60 | front. [The app's settings](#settings) turn off each of these: the |
| 61 | notifications, the flash and the badge. |
| 62 | |
| 63 | [Chat sounds](/guides/chat/#sounds-and-do-not-disturb) play as on the |
| 64 | site, through the app's own audio. |
| 65 | |
| 66 | ## The window and the tray |
| 67 | |
| 68 | Closing the window hides it; g1t keeps running in the tray (the menu bar |
| 69 | on macOS) so notifications still arrive. Click the tray icon, or its |
| 70 | **Open g1t**, to bring the window back; on macOS the dock icon does too. |
| 71 | **Quit g1t** in the tray menu ends it. The window remembers its size and |
| 72 | place. To have closing the window quit instead, turn off **Keep g1t |
| 73 | running when the window closes** in [the app's settings](#settings). |
| 74 | |
| 75 | The tray menu also holds **Settings…**, **Check for updates…**, **Use |
| 76 | another g1t…** and, when an update is downloaded, **Restart to update**. |
| 77 | |
| 78 | ### The menu |
| 79 | |
| 80 | The app has the menus a desktop app has: under the window's title on |
| 81 | Windows and Linux, at the top of the screen on macOS. |
| 82 | |
| 83 | | Menu | What is in it | |
| 84 | | --- | --- | |
| 85 | | **File** (**g1t** on macOS) | **Settings** (Ctrl+, or ⌘,), **Use another g1t…**, **Close window** (Ctrl+W), **Quit g1t** (Ctrl+Q or ⌘Q) | |
| 86 | | **Edit** | Undo, redo, cut, copy, paste and select all | |
| 87 | | **View** | **Reload** (Ctrl+R), **Actual size** (Ctrl+0), **Zoom in** (Ctrl+=), **Zoom out** (Ctrl+-), full screen | |
| 88 | | **Go** | **Back** (Alt+Left, or ⌘[), **Forward** (Alt+Right, or ⌘]), **Home**, **Notifications** | |
| 89 | | **Window** | Minimize and maximize | |
| 90 | | **Help** | **Desktop app guide** and **g1t.sh status**, in your browser; **Check for updates…**; **Restart to update**, once one is downloaded; **About g1t** | |
| 91 | |
| 92 | On Windows and Linux, **Show the menu bar** in the settings hides it; the |
| 93 | tray's **Settings…** and your account menu still open the settings to bring |
| 94 | it back. |
| 95 | |
| 96 | ## Settings |
| 97 | |
| 98 | The app's own settings are in a window of their own: **Settings** in the |
| 99 | File menu (the g1t menu on macOS), **Settings…** in the tray, or **Desktop |
| 100 | app settings** in your account menu on g1t. Each change takes effect at |
| 101 | once and is kept on this computer. Your account's settings, which things |
| 102 | notify you among them, stay on g1t, in [your settings](/guides/notifications/#settings). |
| 103 | |
| 104 | | Setting | Default | What it does | |
| 105 | | --- | --- | --- | |
| 106 | | **Open g1t when you sign in** | Off | Starts g1t with your computer. The system keeps this: a login item on macOS, a startup entry on Windows, an autostart entry on Linux. | |
| 107 | | **Start in the tray** | On | Opened at sign-in, g1t waits in the tray without opening its window. Opening it yourself always shows the window. | |
| 108 | | **Keep g1t running when the window closes** | On | Closing the window leaves g1t in the tray for notifications. Off, closing the window quits. | |
| 109 | | **Show notifications** | On | Notifications from your system. Off, nothing pops up from the app, whatever your account's settings say. | |
| 110 | | **Flash the taskbar icon** (**Bounce the dock icon** on macOS) | On | Asks for your attention with a notification while the window is not in front. | |
| 111 | | **Show a badge on the icon** | On | The count, or the dot on Windows. Off, the icon stays clean; the tray's hover text still counts. | |
| 112 | | **Show the menu bar** | On | Windows and Linux only. | |
| 113 | | **Zoom** | 100% | How large g1t is drawn, from 67% to 200%. The View menu changes it too. | |
| 114 | | **Download updates by themselves** | On | Off, the app never checks on its own; **Check for updates** still does. | |
| 115 | |
| 116 | The settings window also shows the app's version and whether it is up to |
| 117 | date, with **Check for updates** (see [Updates](#updates)), and the server it opens, with **Change…** to [use another |
| 118 | g1t](#your-own-g1t). |
| 119 | |
| 120 | ## Links |
| 121 | |
| 122 | A **`g1t://` link** opens a page in the app: `g1t://acme/-/chat/dm/chn_1` |
| 123 | is `g1t.sh/acme/-/chat/dm/chn_1`. The installer registers the scheme; a |
| 124 | link opened while the app is running moves it to the page without a |
| 125 | reload, and one opened while it is not starts it there. Scripts, launchers |
| 126 | and other apps on your computer can use it. |
| 127 | |
| 128 | A link to another site opens in the browser your system uses; the window |
| 129 | stays on g1t. That includes this documentation and the status page. So do |
| 130 | g1t's own pages for reading about g1t rather than using it: pricing, the |
| 131 | policies, security, support and the downloads. Links on g1t that would |
| 132 | open a new tab open in the window instead, as it has no tabs. Signing in |
| 133 | with GitHub is the one trip outside g1t that stays in the window. |
| 134 | |
| 135 | ## Updates |
| 136 | |
| 137 | The app asks `g1t.sh/downloads/desktop/latest.json` for a newer version |
| 138 | shortly after it starts and every six hours, and downloads one in the |
| 139 | background. It never installs under you: a notification and the tray's |
| 140 | **Restart to update** say it is ready, and the restart, or quitting, |
| 141 | installs it. |
| 142 | |
| 143 | To see where your copy stands, choose **Check for updates…** in the Help |
| 144 | menu or the tray, or **Check for updates** in [the settings](#settings). |
| 145 | The menu and the tray open the settings window at its Updates section, |
| 146 | which checks and says the answer there: |
| 147 | |
| 148 | - **Up to date. Last checked today at 10:42.** You have the newest version. |
| 149 | - **Version 0.2.0 is downloaded and installs when g1t restarts.** A |
| 150 | **Restart now** button beside it installs it and opens the new version, |
| 151 | as **Restart to update** in the Help menu and the tray do. |
| 152 | - **Could not reach g1t.sh to check.** Try again once you are online. |
| 153 | |
| 154 | A check finds and downloads a new version in one go, so the answer can |
| 155 | take a moment on a slow connection. The automatic checks and yours are the |
| 156 | same check: a version the background found is shown as downloaded when |
| 157 | you look. To stop the app checking on its own, turn off |
| 158 | **Download updates by themselves** in [the settings](#settings). |
| 159 | |
| 160 | Every release is signed with g1t's key, whose public half is built into |
| 161 | the app; a download whose signature does not check out is thrown away. |
| 162 | Because the window shows the site itself, most changes to g1t need no |
| 163 | update at all: the app updates when something native changes. |
| 164 | |
| 165 | ## Your own g1t |
| 166 | |
| 167 | If you [run g1t yourself](/guides/self-hosting/), point the app at it: |
| 168 | **Use another g1t…** in the tray or the File menu, or **Change…** in [the |
| 169 | settings](#settings), then your server's address, such as |
| 170 | `https://g1t.example.com`. The app keeps it and opens there from then on; |
| 171 | **Use g1t.sh** on the same page goes back. Only that server's pages can |
| 172 | talk to the app, whichever it is, and updates still come from g1t.sh. |
| 173 | |
| 174 | ## What's not there yet |
| 175 | |
| 176 | - **A runner inside the app**, so an agent can work on your own machine |
| 177 | with what only it reaches, as [the runners page](/guides/self-hosted-runners/) |
| 178 | says. The self-hosted runner works on the same machine meanwhile. |
| 179 | - **Opening the conversation from a notification.** Clicking one brings |
| 180 | the app forward; the page it is about is coming. |
| 181 | - **A page of its own while offline.** If the network goes away while a |
| 182 | page is open, the window shows the web view's own error until it is |
| 183 | back; starting without a network shows the app's own page, with a retry. |
| 184 | - **Notarization on macOS**, so the first open needs no right-click. |
| 185 | - **A phone app.** It is being built: see [the phone app](/guides/mobile/). |
| 186 | |
| 187 | ## For operators: releasing the app |
| 188 | |
| 189 | The app lives in `apps/desktop` in [g1t's repository](https://g1t.sh/flagon-io/g1t): |
| 190 | a Tauri shell in Rust under `src-tauri`, and a launcher page it bundles. |
| 191 | A release is a tag `desktop-v<version>`, where the version is the one in |
| 192 | `apps/desktop/src-tauri/Cargo.toml`: push it, and the `Desktop release` |
| 193 | workflow builds the installers, signs the updater's files, publishes the |
| 194 | release to the `g1t-downloads` bucket and points `latest.json` at it. |
| 195 | `scripts/desktop-release.mjs` does the same by hand, and its header lists |
| 196 | the files a release holds. |
| 197 | |
| 198 | | What | Where | |
| 199 | | --- | --- | |
| 200 | | The updater's signing key | `node scripts/desktop-release.mjs keygen`, once. The private key is the repository secret `DESKTOP_SIGNING_KEY`; the public key is `plugins.updater.pubkey` in `tauri.conf.json`. Losing the private key means every installed app stops updating: keep it. | |
| 201 | | Linux builds | g1t's own Linux machines, in every release. | |
| 202 | | Windows builds | Either a Windows machine registered as a [self-hosted runner](/guides/self-hosted-runners/) with the labels `self-hosted` and `windows` (Rust, Node and the Visual Studio build tools on it) and the repository variable `DESKTOP_WINDOWS_RUNNER` set to `true`; or, with no Windows machine, `DESKTOP_WINDOWS_FROM_LINUX` set to `true`, which cross-builds on Linux with `cargo-xwin` and NSIS and needs `aka.ms` and `download.visualstudio.microsoft.com` among the project's [workflow-only domains](/guides/guardrails/#workflow-only-domains) for `desktop-release.yml` in `production`, where the MSVC runtime is fetched from. | |
| 203 | | macOS builds | A Mac, registered as a self-hosted runner with the labels `self-hosted` and `macos`, and the repository variable `DESKTOP_MACOS_RUNNER` set to `true`. | |
| 204 | | A platform with no machine | Its job is skipped and the release goes out with the rest; the download page says which platforms a release lacks, and the next release fills them in. | |
| 205 | | Where releases are served | `g1t.sh/downloads/desktop/<version>/<file>`, from the same bucket as the runner's and the CLI's releases. | |
| 206 | |
| 207 | A self-hosted g1t does not serve the app's releases: the app always |
| 208 | updates from g1t.sh, and `g1t.sh/download` is where to send people. |