flagon-io/g1t

public

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, artifacts and code,
8	exactly as in a browser, so every change to g1t reaches the app the moment
9	it is deployed. What the app adds is what a browser cannot do:
10
11	- Notifications from your system, for a message to you or a mention,
12	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. The page opens on the system you visit it
29	from, with every other platform a tab away, and lists the
30	[runner](/guides/self-hosted-runners/) and the g1t CLI for each system
31	under Command line.
32
33	## Install
34
35	\| Platform \| What you get \| Notes \|
36	\| --- \| --- \| --- \|
37	\| 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. \|
38	\| 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. \|
39	\| 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. \|
40
41	Every file's SHA-256 is in `SHA256SUMS` beside it, at
42	`https://g1t.sh/downloads/desktop/<version>/`.
43
44	The app opens on g1t.sh's sign-in page, not the site's landing page: it
45	is for using g1t, not for reading about it. It keeps you signed in like a
46	browser does, and signing out brings you back to the sign-in page.
47	Signing in with GitHub goes to github.com and comes back inside the
48	window.
49
50	## Notifications and the badge
51
52	Inside the app, the Desktop notifications switch in
53	[Settings → Notifications](/guides/notifications/#settings) is on and the
54	app shows them itself: while the window is behind another or hidden, a
55	message to you shows as a notification from your system, under the same
56	rules as in a browser: [what you chose to be told about](/guides/chat/#notifications),
57	never while [Do not disturb](/guides/chat/#sounds-and-do-not-disturb) is
58	on, never for a muted conversation. With the window in front, the pop-up
59	in the corner shows instead, as on the site. Clicking a notification
60	brings the app forward; opening the conversation it is about from the
61	notification is coming.
62
63	The icon carries a badge with what is waiting for you: the count on macOS
64	and Linux, a lavender dot on Windows. The tray icon's hover text says the
65	number everywhere. With a notification, the taskbar icon flashes on
66	Windows and the dock icon bounces on macOS, while the window is not in
67	front. [The app's settings](#settings) turn off each of these: the
68	notifications, the flash and the badge.
69
70	[Chat sounds](/guides/chat/#sounds-and-do-not-disturb) play as on the
71	site, through the app's own audio.
72
73	## The window and the tray
74
75	Closing the window hides it; g1t keeps running in the tray (the menu bar
76	on macOS) so notifications still arrive. Click the tray icon, or its
77	Open g1t, to bring the window back; on macOS the dock icon does too.
78	Quit g1t in the tray menu ends it. The window remembers its size and
79	place. To have closing the window quit instead, turn off **Keep g1t
80	running when the window closes** in [the app's settings](#settings).
81
82	The tray menu also holds Settings…, Check for updates…, **Use
83	another g1t… and, when an update is downloaded, Restart to update**.
84
85	### The title bar
86
87	g1t draws its own title bar, so the whole window is g1t and looks the
88	same on Windows, macOS and Linux. It takes the colours of g1t's rail, in
89	light and dark.
90
91	\| Part \| What it does \|
92	\| --- \| --- \|
93	\| ☰ (Windows and Linux) \| Opens the app's [menu](#the-menu). \|
94	\| ← → \| Back and forward through the pages you have been on. \|
95	\| Search \| In the middle: searches your workspace, as Ctrl+K or ⌘K does. Before you are signed in, it shows the page's title. \|
96	\| The runner's dot \| At the right, right beside Settings: a small circle in the colour of what [the runner](#the-runner) is doing, live: green while it runs, blue and breathing while it works (Running a job, Runner starting, Runner updating), amber or red when it needs you, grey when it is stopped or off. Hover it for the words; a wide window shows them beside it. It opens [the runner menu](#the-runner-menu). \|
97	\| Settings \| Opens [the settings](#settings) over the page. \|
98	\| 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. \|
99
100	Drag the bar to move the window, and double-click it to maximize or
101	restore it. The bar is there on every page the window shows, signing in
102	with GitHub included, and the page sits below it, never under it.
103
104	To have the system's title bar instead, turn on **Use the system's title
105	bar** in [the settings](#settings). On Windows and Linux the menu bar
106	comes back under it. g1t restarts to change it: the settings offer
107	Restart now.
108
109	### The menu
110
111	The app has the menus a desktop app has: under ☰ at the left of the
112	title bar on Windows and Linux, or under the system's title bar if you
113	use it, and at the top of the screen on macOS. Their shortcuts work
114	either way.
115
116	\| Menu \| What is in it \|
117	\| --- \| --- \|
118	\| File (g1t on macOS) \| Settings (Ctrl+, or ⌘,), Use another g1t…, Close window (Ctrl+W), Quit g1t (Ctrl+Q or ⌘Q) \|
119	\| Edit \| Undo, redo, cut, copy, paste and select all \|
120	\| View \| Reload (Ctrl+R), Actual size (Ctrl+0), Zoom in (Ctrl+=), Zoom out (Ctrl+-), full screen \|
121	\| Go \| Back (Alt+Left, or ⌘[), Forward (Alt+Right, or ⌘]), Home, Notifications \|
122	\| Window \| Minimize and maximize \|
123	\| Help \| Desktop app guide and g1t.sh status, in your browser; Check for updates…; Restart to update, once one is downloaded; About g1t \|
124
125	## Settings
126
127	The app's own settings open over the page you are on, with their
128	sections down the left (Starting and closing, Runner,
129	Notifications, Window, Updates, Server, About) and the
130	one you choose on the right. Open them with the Settings button at the
131	right of the title bar, Settings in the File menu (the g1t menu on
132	macOS) or Ctrl+, (⌘, on macOS), Settings… in the tray, or **Desktop
133	app settings** in your account menu on g1t; the window comes forward if it
134	was hidden. Escape or × closes them. Each change takes effect at once
135	and is kept on this computer; there is nothing to save. Your account's
136	settings, which things notify you among them, stay on g1t, in
137	[your settings](/guides/notifications/#settings).
138
139	While the window shows no page of g1t's, such as the page that picks a
140	server, the page g1t shows when it can't reach the server, or signing in
141	with GitHub, the settings open in a window of their own instead, with the
142	same settings.
143
144	\| Setting \| Default \| What it does \|
145	\| --- \| --- \| --- \|
146	\| 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. \|
147	\| 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. \|
148	\| Keep g1t running when the window closes \| On \| Closing the window leaves g1t in the tray for notifications. Off, closing the window quits. \|
149	\| Show notifications \| On \| Notifications from your system. Off, nothing pops up from the app, whatever your account's settings say. \|
150	\| 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. \|
151	\| 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. \|
152	\| 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. \|
153	\| Zoom \| 100% \| How large g1t is drawn, from 67% to 200%. The View menu changes it too. \|
154	\| 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: off, only Check for runner updates looks for a newer runner. \|
155
156	Updates also shows the app's version and whether it is up to date,
157	with Check for updates (see [Updates](#updates)); Server shows the
158	server it opens, with Change… to [use another g1t](#your-own-g1t); and
159	Runner has [the runner's settings](#runner-settings) and a card for
160	each kind of job.
161
162	A button that asks the app to do something, such as Check for updates,
163	Restart now, Retry, Start or Stop, shows a spinner and
164	can't be pressed again until what it asked for shows: the runner's state
165	changes, the answer comes, or, after 20 seconds with no change, it is
166	yours to press again. If the app couldn't do it, the settings say why.
167
168	## The runner
169
170	The app runs a [self-hosted runner](/guides/self-hosted-runners/) for
171	you while it is open: your workspace's jobs that ask for `self-hosted`
172	run on your computer, at no cost, and nothing has to be downloaded,
173	registered or started by hand. It starts a few seconds after the window
174	opens, and stops when g1t quits. Time on it is free, as on any of your
175	runners.
176
177	To stop it, press Stop in [the runner menu](#the-runner-menu), or
178	Stop running jobs in the tray; it starts again with Start, or the
179	next time g1t opens. To keep it off, turn off **Run jobs on this computer
180	while g1t is open** in [the runner's settings](#runner-settings).
181
182	Sandboxed, each kind of job has its own line in the runner menu and card
183	in the settings, Linux jobs and Windows jobs, each with its own Stop
184	and Start. Stopping Windows jobs leaves Linux jobs running, and the
185	other way round; a kind you stop stays stopped, across restarts, until you
186	start it again. Both are on until you stop one.
187
188	A job still runs only on a runner with every label it names. The app's
189	runner has `self-hosted`, its OS and architecture (`linux` for a runner
190	whose jobs run in containers, whatever the computer is), and `desktop`.
191	It is named after your computer, and a new registration from the same
192	computer takes the place of the old one. Sandboxed, the computer has a
193	runner for each kind of job it can run, named after it with `-linux` or
194	`-windows`: `build-box-linux` has `linux`, and `build-box-windows` has
195	`windows`, on a Windows computer with Windows Sandbox.
196
197	### The runner menu
198
199	The runner's dot, right beside Settings in the title bar, opens its
200	menu, under the dot. The runner's row in the tray opens it too. It shows,
201	live:
202
203	- What the runner is doing, how jobs run, the workspace and the runner's
204	version, with Stop or Start for the whole runner.
205	- When the runner needs you, why, and the fix with its buttons.
206	- Each kind of job, sandboxed: its state, the job it is running with a link
207	to its run, a newer runner waiting for it, why it isn't running and the
208	fix, and its own Stop or Start.
209	- When the app last looked for a newer runner, with **Check for runner
210	updates**.
211	- The last lines of the runner's log, with Open the whole log.
212	- Runner settings…, which opens [the settings](#settings) at Runner.
213
214	Escape, a click outside it, or the dot again closes it. While the window
215	shows no page of g1t's, the dot and the tray open the Runner window
216	instead: the same, in a window of its own.
217
218	### Runner settings
219
220	The settings' Runner section has a card for each kind of job, as the
221	menu has them with more detail (its runner's name on g1t, its version and
222	isolation), and these:
223
224	\| Setting \| Default \| What it does \|
225	\| --- \| --- \| --- \|
226	\| Run jobs on this computer while g1t is open \| On \| Starts the runner a few seconds after the window. Off, nothing runs. \|
227	\| How jobs run \| Sandboxed \| Sandboxed, in Docker, or directly on this computer. See [how jobs run](#how-jobs-run). \|
228	\| Linux jobs, Windows jobs (sandboxed) \| Both on \| Each kind of job's card has its own Stop and Start, which leave the other kind as it is. \|
229	\| Workspace \| The one you were in when it first registered \| The workspace whose jobs the runner runs. Lists the workspaces you own. \|
230
231	Choosing In Docker or Directly on this computer opens the Runner
232	window, a page that comes with the app, and you choose it there. Jobs
233	outside the sandbox can reach your files, so the app takes that choice
234	only from its own pages, never from a page g1t's server sends; going back
235	to Sandboxed works from either.
236
237	[Seeing it](#seeing-it) says what else it shows.
238
239	### How jobs run
240
241	How jobs run, in [the runner's settings](#runner-settings), decides what a job on your computer can
242	reach. The app never changes it by itself: when the one you chose cannot
243	start, it says why and runs nothing.
244
245	\| Choice \| How \| [Isolation](/guides/self-hosted-runners/#isolation) \| What a job can reach \|
246	\| --- \| --- \| --- \| --- \|
247	\| 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. \|
248	\| 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. \|
249	\| 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. \|
250
251	What the sandbox needs on each computer:
252
253	\| Computer \| Linux jobs \| Windows jobs \|
254	\| --- \| --- \| --- \|
255	\| 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. \|
256	\| macOS 13 or later \| [vfkit](https://github.com/crc-org/vfkit): `brew install vfkit` \| Not released yet \|
257	\| Linux \| Sysbox 0.7 or later in Docker, or QEMU with KVM \| None: Linux jobs are native \|
258
259	The sandbox also needs virtualization turned on in your computer's
260	firmware (Intel VT-x or AMD-V), which most computers have on.
261
262	The sandbox keeps jobs from your computer, not your computer from the
263	sandbox: anything running as your account can look inside it while a job
264	runs. So don't choose Directly on this computer under the same
265	account you use for the sandbox, and don't run software you don't trust
266	there. A runner registered for running jobs directly stays registered when
267	you choose another way, so remove it once you no longer use it:
268	`g1t-runner remove --dir <data folder>/host`, with the data folder below.
269	`g1t-runner sandbox status` warns while one is there. A job's secrets go from inside the sandbox
270	straight to g1t, the job's token left on your computer is spent once the
271	job has started, and the runner's folders are yours alone. [What your
272	computer can see](/guides/self-hosted-runners/#what-your-computer-can-see)
273	has the details.
274
275	For the sandbox, the app runs the same commands you would, with its own
276	copy of `g1t-runner` and its state in the app's local data folder, which
277	never roams to other computers with your profile
278	(`%LOCALAPPDATA%\sh.g1t.desktop\runner` on Windows, or
279	`%APPDATA%\sh.g1t.desktop\runner` where an earlier version set it up;
280	`~/Library/Application Support/sh.g1t.desktop/runner` on macOS;
281	`~/.local/share/sh.g1t.desktop/runner` on Linux):
282
283	\| When \| The app runs \|
284	\| --- \| --- \|
285	\| A few seconds after g1t opens \| `g1t-runner sandbox up --json --state-dir <data folder>/sandbox --url <server> --name <computer> --labels desktop`, with the registration token the first time only, in its environment as `G1T_RUNNER_TOKEN`, never on its command line, where anyone on the computer could read it. The first `up` downloads and checks the sandbox's image and makes the VM, which takes a few minutes. \|
286	\| Every few seconds while it runs \| `g1t-runner sandbox status --json`, for the tray, the settings and the Runners page. \|
287	\| When g1t quits, or you press Stop running jobs \| `g1t-runner sandbox down`: a job that is running is cut short. \|
288	\| When you press Stop on one kind of job's card \| `g1t-runner sandbox down --only windows` (or `linux`): that kind stops, a job of its own cut short, and stays off; the other runs on. Every `up` names the kinds that are on, `--only linux,windows`, so one you stopped never starts by itself. \|
289	\| When you press Start on one kind of job's card \| `g1t-runner sandbox up --only windows` (or `linux`), leaving the other as it is. A kind never registered is registered first, with a token as above. \|
290	\| While one kind of job runs and the other should and doesn't \| `g1t-runner sandbox up --only` it again, by itself: every five minutes while the newest release has no sandbox images, else after a wait that grows each time, up to ten minutes. Retry or Check now tries at once. \|
291	\| 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. \|
292	\| With a new release, once Linux jobs have no job \| `g1t-runner sandbox update`: the newest signed image, the same registration. Windows jobs run on meanwhile. \|
293	\| With a new release, once Windows jobs have no job \| `g1t-runner sandbox down --only windows --drain`, the new `g1t-runner` put in place, then `g1t-runner sandbox up --only windows`. Their runner is `g1t-runner` itself, so they stop while it is replaced, a few seconds; Linux jobs run on meanwhile. \|
294
295	The other two choices run `g1t-runner` from the same data folder, with
296	each one's registration beside it.
297
298	On Windows the sandbox is the WSL distribution `g1t-sandbox`, of which a
299	computer has one. If this copy of g1t has no record of making the one
300	there (you made it with `g1t-runner sandbox up`, or g1t was uninstalled
301	with its data deleted and installed again), the app leaves it alone and
302	says this computer has another sandbox: Remove it and start again
303	removes it, with its VM and registration, and makes the app's own; or keep
304	it and turn the app's runner off. Uninstalling g1t with **Delete the
305	application data** ticked removes the sandbox too.
306
307	### Registering
308
309	The first time, and whenever you change the workspace or how jobs run,
310	the app registers your computer with the workspace. It needs you signed
311	in to g1t in the app as an owner of the workspace, since only owners add
312	runners: the page you are on makes a registration token, which lasts an
313	hour, and hands it to the app, which gives it to the runner once. The
314	token is never shown, and is not kept. From then on the runner starts
315	from its registration, signed in or not.
316
317	The workspace is the one you were in when it first registered; choose
318	another under Workspace in [the runner's settings](#runner-settings). Changing it, or how jobs
319	run, waits for a job that is running to end, then removes the old
320	registration and makes a new one. The sandbox is registered with one
321	workspace, so moving it to another removes it and makes it again, image
322	and all; its old runners stay listed on g1t, offline, until you remove
323	them there.
324
325	### Keeping it up to date
326
327	The app keeps the runner up to date. Soon after it starts, then every
328	hour, it looks for a newer `g1t-runner` in
329	`g1t.sh/downloads/runner/latest.json`, while the runner carries on:
330
331	1. It checks the release is g1t's. The manifest's Ed25519 signature,
332	`latest.json.sig`, must check out against g1t's release key, which is
333	built into the app. A manifest without one, or whose signature
334	doesn't check out, is refused, and nothing in it is used: the app says
335	Update refused: not signed by g1t and keeps the runner it has.
336	2. It downloads the new `g1t-runner` and checks it against the
337	SHA-256 the signed manifest names, throwing away one that differs.
338	3. It puts it in, one kind of job at a time, as each is idle. A job
339	is never cut short for an update. Sandboxed, Linux jobs take the
340	release's image (`g1t-runner sandbox update`, which checks its
341	signature and SHA-256 itself) as soon as they have no job, and
342	Windows jobs, whose runner is `g1t-runner` itself, stop after their
343	job, take the new program and start again, while the other kind runs
344	on. In Docker or directly on this computer, the runner stops between
345	jobs and starts on the new one.
346
347	Meanwhile each card says what is waiting: *0.3.2 ready, installs after
348	this job. Check for runner updates*, in [the runner menu](#the-runner-menu),
349	looks at once, and installs what it finds the same way. An
350	update that fails leaves the runner as it was, and the next hour's look
351	tries again. Turning off Download updates by themselves stops the
352	hourly look; Check for runner updates still looks, and installs.
353
354	### Seeing it
355
356	\| Where \| What it shows \|
357	\| --- \| --- \|
358	\| The title bar \| Its dot, right beside Settings, in the colour of what it is doing; hover it for the words (Runner running, Running a job, Running 2 jobs, Runner starting, Runner stopped, Runner needs you), which a wide window shows beside it. It opens the runner menu. \|
359	\| The tray \| A row with what the runner is doing, Runner: Waiting for jobs, which opens the runner menu; Stop running jobs or Start running jobs under it. The icon's hover text says it too. \|
360	\| [The runner menu](#the-runner-menu) \| At the top, what the whole runner is doing, as the dot says it, with how jobs run, its workspace and version, and its own Stop or Start. When it needs you, only what is about the whole runner: signed out, no workspace, turned off, stopped, the sandbox down, with the fix's buttons. Sandboxed, a line for each kind of job: its state (Running a job, Waiting for jobs, Starting, Downloading image with how far, Updating, Waiting for image, Stopped, Not available, Problem), the job it is running with a link to it, a newer runner waiting for it (0.3.2 ready, installs after this job), and when it isn't running why and the fix, with the fix's buttons and its own Stop or Start. Then when the app last looked for a newer runner, with Check for runner updates; the last lines of its log, following along, with Open the whole log; and Runner settings…. \|
361	\| [The runner's settings](#runner-settings) \| The same, with a card for each kind of job side by side, which adds its runner's name on g1t, version, updates and isolation; then Run jobs on this computer while g1t is open, how jobs run, the workspace, and your computer's name, the runner's version and when the app last looked for a newer one, with View on g1t. In Docker or directly on this computer, one line says what it is doing, or why it isn't running and the fix. \|
362	\| 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; a sandboxed one's kinds of job as cards of their own, as in the settings, with a link to the run each is running, its version, when the app last looked for updates and a newer one waiting. Inside the app, this computer comes first, live, with its buttons, each kind's Stop or Start and Check for runner updates among them. A computer whose g1t is closed says g1t is closed on its name. \|
363
364	### When it isn't running
365
366	Each state says why, and how to fix it, in the same words in the tray,
367	the settings and the Runners page.
368
369	\| It says \| Why \| What to do \|
370	\| --- \| --- \| --- \|
371	\| Waiting for jobs \| It is registered and listening. \| Nothing. \|
372	\| Running a job \| It is running that job. \| Nothing; the Runners page links to its run. \|
373	\| Starting, Registering with a workspace, Updating \| It is on its way. \| Wait a few seconds. \|
374	\| Not running: turned off \| Run jobs on this computer while g1t is open is off. \| Turn on. \|
375	\| Not running: stopped \| You pressed Stop running jobs in the tray. \| Start, or open g1t again. \|
376	\| Not running: every kind of job is stopped \| You stopped Linux jobs and Windows jobs, each on its card. \| Start on one. \|
377	\| Linux jobs: Stopped, Windows jobs: Stopped, You stopped them \| You pressed Stop on that card. The other kind runs on. \| Start on the card. \|
378	\| Linux jobs: Waiting for image: Waiting for the sandbox's image \| The newest `g1t-runner` is published without the sandbox's images yet (or without this kind of computer's), so there is nothing to download. \| Nothing: g1t looks again every five minutes and starts Linux jobs once they're out. Check now looks at once. \|
379	\| Not running: signed out \| It isn't registered yet, and registering needs you signed in. \| Sign in, as an owner of the workspace. \|
380	\| 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. \|
381	\| 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. \|
382	\| 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. \|
383	\| 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. \|
384	\| 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. \|
385	\| 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. \|
386	\| 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. \|
387	\| 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. \|
388	\| 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. \|
389	\| Not running: the sandbox's image didn't download \| The image couldn't be fetched from g1t, with the reason. \| It tries again by itself, waiting longer each time; check that your computer can reach g1t. Retry tries now. \|
390	\| Not running: the sandbox's image didn't check out \| The image that downloaded isn't the one the release signed (its signature or SHA-256), so it wasn't used. \| It downloads it again by itself. If it keeps happening, something between your computer and g1t, such as a proxy or antivirus, is changing downloads: Report it. \|
391	\| Not running: the sandbox can't run here \| Something else the sandbox needs, in its own words. \| What it says. \|
392	\| 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. \|
393	\| Not running: this computer has another sandbox \| A sandbox this copy of g1t has no record of making: one you made with `g1t-runner sandbox up`, or one left from before g1t was installed again. A computer has one. \| Remove it and start again, which asks first; its old runners stay listed on g1t, offline, until you remove them there. Or keep it, and turn the app's runner off. \|
394	\| 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. \|
395	\| Windows jobs: Not available: Windows Sandbox is off, Windows needs an update \| 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. \|
396	\| Windows jobs: Problem: Its runner didn't start or Its runner stopped \| The runner for Windows jobs didn't start, with why, or stopped by itself, while Linux jobs run. \| It is started again by itself in a few minutes; Retry now, or View log. \|
397	\| macOS jobs: Not available: Not released yet \| Sandboxed macOS jobs aren't released. \| Nothing: they come with a `g1t-runner` update, which the app downloads by itself. \|
398	\| Offline: the server unreachable \| Your computer can't reach g1t. \| Check the connection; it carries on by itself. Retry tries now. \|
399	\| 0.3.2 ready, installs after this job, on a card \| A newer `g1t-runner` is downloaded and checked, and that kind of job is running a job. \| Nothing: it goes in as soon as the job ends, and the other kind runs on meanwhile. \|
400	\| Update failed \| A new version couldn't be downloaded, its SHA-256 wasn't the release's, or the sandbox's image couldn't be updated. \| It keeps running the version it has, and tries again within the hour. Check again now; Report it if it keeps failing. \|
401	\| Update refused: not signed by g1t \| The newest release's manifest has no signature, or one that isn't g1t's release key's, so nothing in it was used. \| Nothing to fix on your side: it keeps running the version it has, and looks again within the hour (Check again looks now). If it keeps happening, something between your computer and g1t, such as a proxy or antivirus, is changing downloads: Report it. \|
402	\| Not running: the runner's release isn't signed by g1t \| As above, before any `g1t-runner` was installed, so there is none to run. \| It tries again by itself in a few minutes; Retry now, or Report it if it keeps happening. \|
403	\| 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. \|
404	\| 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. \|
405
406	## Links
407
408	A `g1t://` link opens a page in the app: `g1t://acme/-/chat/dm/chn_1`
409	is `g1t.sh/acme/-/chat/dm/chn_1`. The installer registers the scheme; a
410	link opened while the app is running moves it to the page without a
411	reload, and one opened while it is not starts it there. Scripts, launchers
412	and other apps on your computer can use it.
413
414	A link to another site opens in the browser your system uses; the window
415	stays on g1t. That includes this documentation and the status page. So do
416	g1t's own pages for reading about g1t rather than using it: pricing, the
417	policies, security, support and the downloads. Links on g1t that would
418	open a new tab open in the window instead, as it has no tabs. Signing in
419	with GitHub is the one trip outside g1t that stays in the window.
420
421	## Updates
422
423	The app asks `g1t.sh/downloads/desktop/latest.json` for a newer version
424	as it starts and every hour, and downloads one in the background.
425
426	- As it starts, a newer version is installed straight away, and g1t
427	opens again on it a moment later, before you have begun working in it.
428	If something in the app misbehaves, quitting and opening g1t again is
429	enough to be on the newest version. The one exception is your runner
430	in the middle of a job, which is never cut short: then the update waits
431	like any other.
432	- Later on, it never installs under you: a notification and the
433	tray's Restart to update say it is ready, and the restart, or
434	quitting, installs it.
435
436	To see where your copy stands, choose Check for updates… in the Help
437	menu or the tray, or Check for updates in [the settings](#settings).
438	The menu and the tray open the settings at their Updates section,
439	which checks and says the answer there:
440
441	- Up to date. Last checked today at 10:42. You have the newest version.
442	- Version 0.2.0 is downloaded and installs when g1t restarts. A
443	Restart now button beside it installs it and opens the new version,
444	as Restart to update in the Help menu and the tray do.
445	- Could not reach g1t.sh to check. Try again once you are online.
446
447	A check finds and downloads a new version in one go, so the answer can
448	take a moment on a slow connection. The automatic checks and yours are the
449	same check: a version the background found is shown as downloaded when
450	you look. To stop the app checking on its own, turn off
451	Download updates by themselves in [the settings](#settings).
452
453	Every release is signed with g1t's key, whose public half is built into
454	the app; a download whose signature does not check out is thrown away.
455	Because the window shows the site itself, most changes to g1t need no
456	update at all: the app updates when something native changes.
457
458	## Your own g1t
459
460	If you [run g1t yourself](/guides/self-hosting/), point the app at it:
461	Use another g1t… in the tray or the File menu, or Change… in [the
462	settings](#settings), then your server's address, such as
463	`https://g1t.example.com`. The app keeps it and opens there from then on;
464	Use g1t.sh on the same page goes back. Only that server's pages can
465	talk to the app, whichever it is, and updates still come from g1t.sh.
466
467	## What's not there yet
468
469	- Windows jobs on a Mac. Sandboxed macOS jobs are designed, not
470	released, so a Mac's sandbox runs Linux jobs only.
471	- Choosing the sandbox's share of the computer. It takes half the
472	CPUs (at most 8) and a quarter of the memory (2 to 8 GB); the app has no
473	setting for it yet.
474	- Opening the conversation from a notification. Clicking one brings
475	the app forward; the page it is about is coming.
476	- A page of its own while offline. If the network goes away while a
477	page is open, the window shows the web view's own error until it is
478	back; starting without a network shows the app's own page, with a retry.
479	- Notarization on macOS, so the first open needs no right-click.
480	- A phone app. It is being built: see [the phone app](/guides/mobile/).
481
482	## For operators: releasing the app
483
484	The app lives in `apps/desktop` in [g1t's repository](https://g1t.sh/flagon-io/g1t):
485	a Tauri shell in Rust under `src-tauri`, and a launcher page it bundles.
486	A release is a tag `desktop-v<version>`, where the version is the one in
487	`apps/desktop/src-tauri/Cargo.toml`: push it, and the `Desktop release`
488	workflow builds the installers, signs the updater's files, publishes the
489	release to the `g1t-downloads` bucket and points `latest.json` at it.
490	`scripts/desktop-release.mjs` does the same by hand, and its header lists
491	the files a release holds.
492
493	\| What \| Where \|
494	\| --- \| --- \|
495	\| The runner's release key \| The app trusts a `g1t-runner` release only when its manifest is signed with g1t's runner release key, whose public half (the repository variable `RUNNER_RELEASE_PUBLIC_KEY`) is built into the app, in `src-tauri/src/runner/native.rs`. To build the app for a g1t of your own, whose runner releases you sign with your own key, set `G1T_RUNNER_RELEASE_KEY` to its public key, base64, when you build it. \|
496	\| 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. \|
497	\| Linux builds \| g1t's own Linux machines, in every release. \|
498	\| 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. \|
499	\| 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`. \|
500	\| 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. \|
501	\| Where releases are served \| `g1t.sh/downloads/desktop/<version>/<file>`, from the same bucket as the runner's and the CLI's releases. \|
502
503	A self-hosted g1t does not serve the app's releases: the app always
504	updates from g1t.sh, and `g1t.sh/download` is where to send people.