flagon-io/g1t

public

Where people and agents ship software together. The open-source git platform for the whole job: issues, agents, checks and deploys to the edge.

g1t.sh

git agents cloudflare rust forge mcp

521 linesCode BlameRaw

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