| 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, a runner for your workspace's jobs, 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 | - **A runner for your workspace**, started with the app, so your |
| 21 | computer runs the workspace's `runs-on: self-hosted` jobs while g1t is |
| 22 | open, with nothing to install or register. See [the runner](#the-runner). |
| 23 | - **Settings of its own**: opening when you sign in to your computer, |
| 24 | what closing the window does, notifications, the badge, zoom, updates |
| 25 | and the runner. |
| 26 | |
| 27 | Get it at [g1t.sh/download](https://g1t.sh/download), or from your account |
| 28 | menu, **Get the desktop app**. |
| 29 | |
| 30 | ## Install |
| 31 | |
| 32 | | Platform | What you get | Notes | |
| 33 | | --- | --- | --- | |
| 34 | | **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. | |
| 35 | | **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**. | |
| 36 | | **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. | |
| 37 | |
| 38 | Every file's SHA-256 is in `SHA256SUMS` beside it, at |
| 39 | `https://g1t.sh/downloads/desktop/<version>/`. |
| 40 | |
| 41 | The app opens on g1t.sh's sign-in page, not the site's landing page: it |
| 42 | is for using g1t, not for reading about it. It keeps you signed in like a |
| 43 | browser does, and signing out brings you back to the sign-in page. |
| 44 | Signing in with GitHub goes to github.com and comes back inside the |
| 45 | window. |
| 46 | |
| 47 | ## Notifications and the badge |
| 48 | |
| 49 | Inside the app, the **Desktop notifications** switch in |
| 50 | [Settings → Notifications](/guides/notifications/#settings) is on and the |
| 51 | app shows them itself: while the window is behind another or hidden, a |
| 52 | message to you shows as a notification from your system, under the same |
| 53 | rules as in a browser: [what you chose to be told about](/guides/chat/#notifications), |
| 54 | never while [Do not disturb](/guides/chat/#sounds-and-do-not-disturb) is |
| 55 | on, never for a muted conversation. With the window in front, the pop-up |
| 56 | in the corner shows instead, as on the site. Clicking a notification |
| 57 | brings the app forward; opening the conversation it is about from the |
| 58 | notification is coming. |
| 59 | |
| 60 | The icon carries a badge with what is waiting for you: the count on macOS |
| 61 | and Linux, a lavender dot on Windows. The tray icon's hover text says the |
| 62 | number everywhere. With a notification, the taskbar icon flashes on |
| 63 | Windows and the dock icon bounces on macOS, while the window is not in |
| 64 | front. [The app's settings](#settings) turn off each of these: the |
| 65 | notifications, the flash and the badge. |
| 66 | |
| 67 | [Chat sounds](/guides/chat/#sounds-and-do-not-disturb) play as on the |
| 68 | site, through the app's own audio. |
| 69 | |
| 70 | ## The window and the tray |
| 71 | |
| 72 | Closing the window hides it; g1t keeps running in the tray (the menu bar |
| 73 | on macOS) so notifications still arrive. Click the tray icon, or its |
| 74 | **Open g1t**, to bring the window back; on macOS the dock icon does too. |
| 75 | **Quit g1t** in the tray menu ends it. The window remembers its size and |
| 76 | place. To have closing the window quit instead, turn off **Keep g1t |
| 77 | running when the window closes** in [the app's settings](#settings). |
| 78 | |
| 79 | The tray menu also holds **Settings…**, **Check for updates…**, **Use |
| 80 | another g1t…** and, when an update is downloaded, **Restart to update**. |
| 81 | |
| 82 | ### The title bar |
| 83 | |
| 84 | g1t draws its own title bar, as Slack and Discord do, so the whole window |
| 85 | is g1t and looks the same on Windows, macOS and Linux. It takes the |
| 86 | colours of g1t's rail, in light and dark. |
| 87 | |
| 88 | | Part | What it does | |
| 89 | | --- | --- | |
| 90 | | **☰** (Windows and Linux) | Opens the app's [menu](#the-menu). | |
| 91 | | **← →** | Back and forward through the pages you have been on. | |
| 92 | | **Search** | In the middle: searches your workspace, as **Ctrl+K** or **⌘K** does. Before you are signed in, it shows the page's title. | |
| 93 | | **Minimize, maximize, close** (Windows and Linux) | At the right. Close keeps g1t in the tray unless [the settings](#settings) say it quits. On macOS the window's own buttons sit at the left of the bar. | |
| 94 | |
| 95 | Drag the bar to move the window, and double-click it to maximize or |
| 96 | restore it. The bar is there on every page the window shows, signing in |
| 97 | with GitHub included, and the page sits below it, never under it. |
| 98 | |
| 99 | To have the system's title bar instead, turn on **Use the system's title |
| 100 | bar** in [the settings](#settings). On Windows and Linux the menu bar |
| 101 | comes back under it. g1t restarts to change it: the settings window offers |
| 102 | **Restart now**. |
| 103 | |
| 104 | ### The menu |
| 105 | |
| 106 | The app has the menus a desktop app has: under **☰** at the left of the |
| 107 | title bar on Windows and Linux, or under the system's title bar if you |
| 108 | use it, and at the top of the screen on macOS. Their shortcuts work |
| 109 | either way. |
| 110 | |
| 111 | | Menu | What is in it | |
| 112 | | --- | --- | |
| 113 | | **File** (**g1t** on macOS) | **Settings** (Ctrl+, or ⌘,), **Use another g1t…**, **Close window** (Ctrl+W), **Quit g1t** (Ctrl+Q or ⌘Q) | |
| 114 | | **Edit** | Undo, redo, cut, copy, paste and select all | |
| 115 | | **View** | **Reload** (Ctrl+R), **Actual size** (Ctrl+0), **Zoom in** (Ctrl+=), **Zoom out** (Ctrl+-), full screen | |
| 116 | | **Go** | **Back** (Alt+Left, or ⌘[), **Forward** (Alt+Right, or ⌘]), **Home**, **Notifications** | |
| 117 | | **Window** | Minimize and maximize | |
| 118 | | **Help** | **Desktop app guide** and **g1t.sh status**, in your browser; **Check for updates…**; **Restart to update**, once one is downloaded; **About g1t** | |
| 119 | |
| 120 | |
| 121 | ## Settings |
| 122 | |
| 123 | The app's own settings are in a window of their own: **Settings** in the |
| 124 | File menu (the g1t menu on macOS), **Settings…** in the tray, or **Desktop |
| 125 | app settings** in your account menu on g1t. Each change takes effect at |
| 126 | once and is kept on this computer. Your account's settings, which things |
| 127 | notify you among them, stay on g1t, in [your settings](/guides/notifications/#settings). |
| 128 | |
| 129 | | Setting | Default | What it does | |
| 130 | | --- | --- | --- | |
| 131 | | **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. | |
| 132 | | **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. | |
| 133 | | **Keep g1t running when the window closes** | On | Closing the window leaves g1t in the tray for notifications. Off, closing the window quits. | |
| 134 | | **Show notifications** | On | Notifications from your system. Off, nothing pops up from the app, whatever your account's settings say. | |
| 135 | | **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. | |
| 136 | | **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. | |
| 137 | | **Use the system's title bar** | Off | The system's title bar in place of [g1t's own](#the-title-bar), with the menu bar under it on Windows and Linux. Takes effect when g1t restarts. | |
| 138 | | **Zoom** | 100% | How large g1t is drawn, from 67% to 200%. The View menu changes it too. | |
| 139 | | **Download updates by themselves** | On | Off, the app never checks on its own; **Check for updates** still does. The runner's updates follow it too. | |
| 140 | | **Run jobs on this computer while g1t is open** | On | Starts [the runner](#the-runner) a few seconds after the window. Off, nothing runs. | |
| 141 | | **How jobs run** | Sandboxed | Sandboxed, in Docker, or directly on this computer. See [how jobs run](#how-jobs-run). | |
| 142 | | **Workspace** | The one you were in when it first registered | The workspace whose jobs the runner runs. Lists the workspaces you own. | |
| 143 | |
| 144 | The settings window also shows the app's version and whether it is up to |
| 145 | date, with **Check for updates** (see [Updates](#updates)), and the server it opens, with **Change…** to [use another |
| 146 | g1t](#your-own-g1t). |
| 147 | |
| 148 | ## The runner |
| 149 | |
| 150 | The app runs a [self-hosted runner](/guides/self-hosted-runners/) for |
| 151 | you while it is open: your workspace's jobs that ask for `self-hosted` |
| 152 | run on your computer, at no cost, and nothing has to be downloaded, |
| 153 | registered or started by hand. It starts a few seconds after the window |
| 154 | opens, and stops when g1t quits. Time on it is free, as on any of your |
| 155 | runners. |
| 156 | |
| 157 | To stop it, press **Stop** in the settings window's Runner section, or |
| 158 | **Stop running jobs** in the tray; it starts again with **Start**, or the |
| 159 | next time g1t opens. To keep it off, turn off **Run jobs on this computer |
| 160 | while g1t is open** in [the settings](#settings). |
| 161 | |
| 162 | A job still runs only on a runner with every label it names. The app's |
| 163 | runner has `self-hosted`, its OS and architecture (`linux` for a runner |
| 164 | whose jobs run in containers, whatever the computer is), and `desktop`. |
| 165 | It is named after your computer, and a new registration from the same |
| 166 | computer takes the place of the old one. Sandboxed, the computer has a |
| 167 | runner for each kind of job it can run, named after it with `-linux` or |
| 168 | `-windows`: `build-box-linux` has `linux`, and `build-box-windows` has |
| 169 | `windows`, on a Windows computer with Windows Sandbox. |
| 170 | |
| 171 | ### How jobs run |
| 172 | |
| 173 | **How jobs run** in the settings decides what a job on your computer can |
| 174 | reach. The app never changes it by itself: when the one you chose cannot |
| 175 | start, it says why and runs nothing. |
| 176 | |
| 177 | | Choice | How | [Isolation](/guides/self-hosted-runners/#isolation) | What a job can reach | |
| 178 | | --- | --- | --- | --- | |
| 179 | | **Sandboxed** (the default) | [The sandbox](/guides/self-hosted-runners/#sandbox-on-your-computer), which the app sets up and starts itself. Linux jobs run in a small Linux VM of the runner's own, each in a container inside it: a WSL 2 distribution on Windows, a VM under Apple's Virtualization framework on macOS, and on Linux the runner's image under [Sysbox](https://github.com/nestybox/sysbox), or a VM under QEMU with KVM. On Windows 11 Pro, Enterprise and Education, Windows jobs run too, each in a Windows Sandbox of its own. | `nested-container`; `vm` for Windows jobs | Its own container, or its own Windows Sandbox. Not your computer. | |
| 180 | | **In Docker** | `g1t-runner` on your computer, driving your Docker. Each job is a container of its own. | `container` | Its own container; but the runner controls your Docker, which can reach your files (Docker Desktop shares your home folder with its VM), so this is not a sandbox. | |
| 181 | | **Directly on this computer** | `g1t-runner` on your computer, each job a process in a folder of its own. For jobs that need the system itself, such as building a Windows installer. | `host` | Everything your account can: your files, your keys, what an earlier job left. Not a sandbox. Never given a public repository's work. | |
| 182 | |
| 183 | What the sandbox needs on each computer: |
| 184 | |
| 185 | | Computer | Linux jobs | Windows jobs | |
| 186 | | --- | --- | --- | |
| 187 | | Windows 11, any edition | WSL, installed once: `wsl --install --no-distribution` in an admin terminal, then a restart. The app's **Copy command** button copies it. | Windows Sandbox, on Pro, Enterprise and Education, version 24H2 or later, turned on in Windows features. Home has none, and Linux jobs still run. | |
| 188 | | macOS 13 or later | [vfkit](https://github.com/crc-org/vfkit): `brew install vfkit` | Not released yet | |
| 189 | | Linux | Sysbox 0.7 or later in Docker, or QEMU with KVM | None: Linux jobs are native | |
| 190 | |
| 191 | The sandbox also needs virtualization turned on in your computer's |
| 192 | firmware (Intel VT-x or AMD-V), which most computers have on. |
| 193 | |
| 194 | For the sandbox, the app runs the same commands you would, with its own |
| 195 | copy of `g1t-runner` and its state in the app's data folder |
| 196 | (`%APPDATA%\sh.g1t.desktop\runner` on Windows, |
| 197 | `~/Library/Application Support/sh.g1t.desktop/runner` on macOS, |
| 198 | `~/.local/share/sh.g1t.desktop/runner` on Linux): |
| 199 | |
| 200 | | When | The app runs | |
| 201 | | --- | --- | |
| 202 | | A few seconds after g1t opens | `g1t-runner sandbox up --json --state-dir <data folder>/sandbox --url <server> --name <computer> --labels desktop`, with `--token` the first time only. The first `up` downloads and checks the sandbox's image and makes the VM, which takes a few minutes. | |
| 203 | | Every few seconds while it runs | `g1t-runner sandbox status --json`, for the tray, the settings and the Runners page. | |
| 204 | | When g1t quits, or you press **Stop** | `g1t-runner sandbox down`: a job that is running is cut short. | |
| 205 | | When you choose another way of running jobs | `g1t-runner sandbox down --drain`, once the job that is running ends. The sandbox keeps its registration, so choosing Sandboxed again needs no new one. | |
| 206 | | With a new release, while it has no job | `g1t-runner sandbox update`: the newest signed image, the same registration. | |
| 207 | |
| 208 | The other two choices run `g1t-runner` from the same data folder, with |
| 209 | each one's registration beside it. |
| 210 | |
| 211 | On Windows the sandbox is the WSL distribution `g1t-sandbox`, of which a |
| 212 | computer has one. If you made one yourself with `g1t-runner sandbox up`, |
| 213 | the app leaves it alone and says *this computer has another sandbox*: |
| 214 | remove it with `g1t-runner sandbox down --delete` for the app to make its |
| 215 | own, or keep it and turn the app's runner off. |
| 216 | |
| 217 | ### Registering |
| 218 | |
| 219 | The first time, and whenever you change the workspace or how jobs run, |
| 220 | the app registers your computer with the workspace. It needs you signed |
| 221 | in to g1t in the app as an owner of the workspace, since only owners add |
| 222 | runners: the page you are on makes a registration token, which lasts an |
| 223 | hour, and hands it to the app, which gives it to the runner once. The |
| 224 | token is never shown, and is not kept. From then on the runner starts |
| 225 | from its registration, signed in or not. |
| 226 | |
| 227 | The workspace is the one you were in when it first registered; choose |
| 228 | another under **Workspace** in the settings. Changing it, or how jobs |
| 229 | run, waits for a job that is running to end, then removes the old |
| 230 | registration and makes a new one. The sandbox is registered with one |
| 231 | workspace, so moving it to another removes it and makes it again, image |
| 232 | and all; its old runners stay listed on g1t, offline, until you remove |
| 233 | them there. |
| 234 | |
| 235 | ### Keeping it up to date |
| 236 | |
| 237 | The app keeps the runner up to date: soon after it starts and every six |
| 238 | hours, while the runner has no job, it looks for a newer `g1t-runner` in |
| 239 | `g1t.sh/downloads/runner/latest.json`, downloads it, checks it against |
| 240 | the release's SHA-256, and puts it in place; the sandbox then takes the |
| 241 | release's image, whose signature and SHA-256 it checks itself. A job is |
| 242 | never cut short for an update, and one that fails leaves the runner as it |
| 243 | was. Turning off **Download updates by themselves** turns these off too. |
| 244 | |
| 245 | ### Seeing it |
| 246 | |
| 247 | | Where | What it shows | |
| 248 | | --- | --- | |
| 249 | | The tray | A row with what the runner is doing, *Runner: Waiting for jobs*, which opens the settings; **Stop running jobs** or **Start running jobs** under it. The icon's hover text says it too. | |
| 250 | | The settings window | What it is doing; when it isn't running, why and how to fix it, with the fix's buttons; sandboxed, a line for each kind of job, *Linux jobs: Waiting for jobs*, *Windows jobs: Not available* and why; how jobs run; the workspace; your computer's name and the runner's version; **View on g1t**; and the runner's recent log, with **Open the whole log**. | |
| 251 | | The workspace's [Runners page](/guides/self-hosted-runners/#the-runners-page) | **Desktops**: every computer with the app in the workspace, with what each is doing, or why it isn't running and the fix, in the same words, and each kind of job a sandboxed one runs. Inside the app, this computer comes first, live, with its buttons. A computer whose g1t is closed says *g1t is closed on* its name. | |
| 252 | |
| 253 | ### When it isn't running |
| 254 | |
| 255 | Each state says why, and how to fix it, in the same words in the tray, |
| 256 | the settings and the Runners page. |
| 257 | |
| 258 | | It says | Why | What to do | |
| 259 | | --- | --- | --- | |
| 260 | | *Waiting for jobs* | It is registered and listening. | Nothing. | |
| 261 | | *Running* a job | It is running that job. | Nothing; the Runners page links to its run. | |
| 262 | | *Starting*, *Registering with* a workspace, *Updating* | It is on its way. | Wait a few seconds. | |
| 263 | | *Not running: turned off* | **Run jobs on this computer while g1t is open** is off. | **Turn on**. | |
| 264 | | *Not running: stopped* | You pressed **Stop**. | **Start**, or open g1t again. | |
| 265 | | *Not running: signed out* | It isn't registered yet, and registering needs you signed in. | **Sign in**, as an owner of the workspace. | |
| 266 | | *Not running: no workspace to run jobs for* | You don't own a workspace, and only owners add runners. | Ask an owner, or **Create a workspace**. | |
| 267 | | *Couldn't register with* a workspace: *only its owners can* | You aren't an owner of it. | Ask an owner to make you one, or **Choose workspace**. | |
| 268 | | *Couldn't register with* a workspace, with g1t's reason | g1t refused the registration, such as for too many tokens in an hour. | **Retry**; it also tries again by itself. | |
| 269 | | *Not running: Docker isn't running* | Running jobs in Docker needs Docker, and it isn't running or isn't installed. | **Open Docker** (Docker Desktop), or **Get Docker**. It starts by itself once Docker answers. | |
| 270 | | *Not running: WSL isn't installed* | Windows: Linux jobs run in a WSL distribution of the runner's own. | Run `wsl --install --no-distribution` in an admin terminal (**Copy command**), then restart Windows. Every edition of Windows 11 has it, Home included. | |
| 271 | | *Not running: WSL uses mirrored networking* | `networkingMode=mirrored` in `%USERPROFILE%\.wslconfig` lets Linux reach your computer's own `localhost`. | Remove it, run `wsl --shutdown`, then **Retry**. | |
| 272 | | *Not running: virtualization is off* | The sandbox is a small VM, and virtualization is off in your computer's firmware, or Virtual Machine Platform is off in Windows features. | Turn them on (**Open Windows features** on Windows), then restart. | |
| 273 | | *Not running: vfkit isn't installed* | macOS: the sandbox's VM runs under vfkit. | Run `brew install vfkit` (**Copy command**). It starts by itself once vfkit is there. | |
| 274 | | *Not running: no Sysbox or KVM* | Linux: the sandbox needs Sysbox in Docker, or QEMU with KVM. | **Install Sysbox**, or turn on virtualization and install QEMU. | |
| 275 | | *Not running: the sandbox's image didn't download* | The image couldn't be fetched, or its signature or SHA-256 wasn't the release's, with the reason. | It tries again by itself; check the connection, or **Report** it. | |
| 276 | | *Not running: the sandbox can't run here* | Something else the sandbox needs, in its own words. | What it says. | |
| 277 | | *Not running: the sandbox failed* | The sandbox stopped, or didn't start, with its reason. | It starts again by itself, waiting longer each time. **Retry**, or **View log**. | |
| 278 | | *Not running: this computer has another sandbox* | A sandbox you made with `g1t-runner sandbox up`; a computer has one. | Remove it with `g1t-runner sandbox down --delete`, then **Retry**; or keep it, and turn the app's runner off. | |
| 279 | | *Not running: this g1t-runner has no sandbox* | The app's `g1t-runner` is from before the sandbox. | It downloads a newer one by itself; **Retry** looks now. | |
| 280 | | *Windows jobs: Not available* | Windows Sandbox is off, this Windows is Home, or it is older than 24H2. Linux jobs still run. | On Pro, Enterprise or Education, turn on Windows Sandbox (**Open Windows features**) and restart, or update Windows. | |
| 281 | | *Offline:* the server *unreachable* | Your computer can't reach g1t. | Check the connection; it carries on by itself. **Retry** tries now. | |
| 282 | | *Update failed* | A new version couldn't be downloaded, or its SHA-256 wasn't the release's. | It keeps running the version it has. **Retry**, or **Report** it. | |
| 283 | | *Runner stopped (exit code* N*)* | The runner ended by itself, with the reason from its log. | It starts again by itself, waiting longer each time. **Restart** now, or **View log**. | |
| 284 | | *g1t is closed on* a computer | Seen on the Runners page: g1t hasn't been open on that computer for ten minutes. | Open g1t there. | |
| 285 | |
| 286 | ## Links |
| 287 | |
| 288 | A **`g1t://` link** opens a page in the app: `g1t://acme/-/chat/dm/chn_1` |
| 289 | is `g1t.sh/acme/-/chat/dm/chn_1`. The installer registers the scheme; a |
| 290 | link opened while the app is running moves it to the page without a |
| 291 | reload, and one opened while it is not starts it there. Scripts, launchers |
| 292 | and other apps on your computer can use it. |
| 293 | |
| 294 | A link to another site opens in the browser your system uses; the window |
| 295 | stays on g1t. That includes this documentation and the status page. So do |
| 296 | g1t's own pages for reading about g1t rather than using it: pricing, the |
| 297 | policies, security, support and the downloads. Links on g1t that would |
| 298 | open a new tab open in the window instead, as it has no tabs. Signing in |
| 299 | with GitHub is the one trip outside g1t that stays in the window. |
| 300 | |
| 301 | ## Updates |
| 302 | |
| 303 | The app asks `g1t.sh/downloads/desktop/latest.json` for a newer version |
| 304 | shortly after it starts and every six hours, and downloads one in the |
| 305 | background. It never installs under you: a notification and the tray's |
| 306 | **Restart to update** say it is ready, and the restart, or quitting, |
| 307 | installs it. |
| 308 | |
| 309 | To see where your copy stands, choose **Check for updates…** in the Help |
| 310 | menu or the tray, or **Check for updates** in [the settings](#settings). |
| 311 | The menu and the tray open the settings window at its Updates section, |
| 312 | which checks and says the answer there: |
| 313 | |
| 314 | - **Up to date. Last checked today at 10:42.** You have the newest version. |
| 315 | - **Version 0.2.0 is downloaded and installs when g1t restarts.** A |
| 316 | **Restart now** button beside it installs it and opens the new version, |
| 317 | as **Restart to update** in the Help menu and the tray do. |
| 318 | - **Could not reach g1t.sh to check.** Try again once you are online. |
| 319 | |
| 320 | A check finds and downloads a new version in one go, so the answer can |
| 321 | take a moment on a slow connection. The automatic checks and yours are the |
| 322 | same check: a version the background found is shown as downloaded when |
| 323 | you look. To stop the app checking on its own, turn off |
| 324 | **Download updates by themselves** in [the settings](#settings). |
| 325 | |
| 326 | Every release is signed with g1t's key, whose public half is built into |
| 327 | the app; a download whose signature does not check out is thrown away. |
| 328 | Because the window shows the site itself, most changes to g1t need no |
| 329 | update at all: the app updates when something native changes. |
| 330 | |
| 331 | ## Your own g1t |
| 332 | |
| 333 | If you [run g1t yourself](/guides/self-hosting/), point the app at it: |
| 334 | **Use another g1t…** in the tray or the File menu, or **Change…** in [the |
| 335 | settings](#settings), then your server's address, such as |
| 336 | `https://g1t.example.com`. The app keeps it and opens there from then on; |
| 337 | **Use g1t.sh** on the same page goes back. Only that server's pages can |
| 338 | talk to the app, whichever it is, and updates still come from g1t.sh. |
| 339 | |
| 340 | ## What's not there yet |
| 341 | |
| 342 | - **Windows jobs on a Mac.** Sandboxed macOS jobs are designed, not |
| 343 | released, so a Mac's sandbox runs Linux jobs only. |
| 344 | - **Choosing the sandbox's share of the computer.** It takes half the |
| 345 | CPUs (at most 8) and a quarter of the memory (2 to 8 GB); the app has no |
| 346 | setting for it yet. |
| 347 | - **Agents on your desktop.** The runner takes workflow jobs, and agent |
| 348 | work only if the workspace [sends it to its runners](/guides/self-hosted-runners/#agents-on-your-runners). |
| 349 | - **Opening the conversation from a notification.** Clicking one brings |
| 350 | the app forward; the page it is about is coming. |
| 351 | - **A page of its own while offline.** If the network goes away while a |
| 352 | page is open, the window shows the web view's own error until it is |
| 353 | back; starting without a network shows the app's own page, with a retry. |
| 354 | - **Notarization on macOS**, so the first open needs no right-click. |
| 355 | - **A phone app.** It is being built: see [the phone app](/guides/mobile/). |
| 356 | |
| 357 | ## For operators: releasing the app |
| 358 | |
| 359 | The app lives in `apps/desktop` in [g1t's repository](https://g1t.sh/flagon-io/g1t): |
| 360 | a Tauri shell in Rust under `src-tauri`, and a launcher page it bundles. |
| 361 | A release is a tag `desktop-v<version>`, where the version is the one in |
| 362 | `apps/desktop/src-tauri/Cargo.toml`: push it, and the `Desktop release` |
| 363 | workflow builds the installers, signs the updater's files, publishes the |
| 364 | release to the `g1t-downloads` bucket and points `latest.json` at it. |
| 365 | `scripts/desktop-release.mjs` does the same by hand, and its header lists |
| 366 | the files a release holds. |
| 367 | |
| 368 | | What | Where | |
| 369 | | --- | --- | |
| 370 | | 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. | |
| 371 | | Linux builds | g1t's own Linux machines, in every release. | |
| 372 | | 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. | |
| 373 | | 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`. | |
| 374 | | 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. | |
| 375 | | Where releases are served | `g1t.sh/downloads/desktop/<version>/<file>`, from the same bucket as the runner's and the CLI's releases. | |
| 376 | |
| 377 | A self-hosted g1t does not serve the app's releases: the app always |
| 378 | updates from g1t.sh, and `g1t.sh/download` is where to send people. |