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

542 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,
25	developer tools, updates 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, Developer tools (Ctrl+Shift+I, or ⌥⌘I), once [turned on](#developer-tools) \|
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	\| Developer tools \| Off \| F12 or Ctrl+Shift+I (⌥⌘I on macOS), and Developer tools in the View menu, open the web inspector for the page. See [Developer tools](#developer-tools). \|
172	\| 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. \|
173
174	Updates also shows the app's version and whether it is up to date,
175	with Check for updates (see [Updates](#updates)); Server shows the
176	server it opens, with Change… to [use another g1t](#your-own-g1t); and
177	Runner has [the runner's settings](#runner-settings) and a card for
178	each kind of job.
179
180	A button that asks the app to do something, such as Check for updates,
181	Restart now, Retry, Start or Stop, shows a spinner and
182	can't be pressed again until what it asked for shows: the runner's state
183	changes, the answer comes, or, after 20 seconds with no change, it is
184	yours to press again. If the app couldn't do it, the settings say why.
185
186	### Developer tools
187
188	When a page goes wrong, such as one that says Something went wrong, the
189	web inspector shows why: the page's console, its network requests and its
190	code. It is off unless you turn on Developer tools in the settings'
191	Window section. Then any of these opens it for the page in the window:
192
193	- F12, on the page.
194	- Ctrl+Shift+I on Windows and Linux, ⌥⌘I (Cmd+Option+I) on macOS.
195	- Developer tools in the View menu.
196
197	On macOS and Linux the same keys, or the menu row, close it again; on
198	Windows, close the inspector's own window. With the setting off, none of
199	them open it, and the View menu's row is greyed out. On Windows the change
200	takes effect at once; on macOS and Linux it takes effect when g1t
201	restarts, and the settings offer Restart now.
202
203	g1t's pages can open it too, from `window.g1tDesktop.devtools.open()`,
204	which works only while the setting is on and only for g1t's own pages.
205
206	## The runner
207
208	The app runs a [self-hosted runner](/guides/self-hosted-runners/) for
209	you while it is open: your workspace's jobs that ask for `self-hosted`
210	run on your computer, at no cost, and nothing has to be downloaded,
211	registered or started by hand. It starts a few seconds after the window
212	opens, and stops when g1t quits. Time on it is free, as on any of your
213	runners.
214
215	To stop it, press Stop in [the runner menu](#the-runner-menu), or
216	Stop running jobs in the tray; it starts again with Start, or the
217	next time g1t opens. To keep it off, turn off **Run jobs on this computer
218	while g1t is open** in [the runner's settings](#runner-settings).
219
220	Sandboxed, each kind of job has its own line in the runner menu and card
221	in the settings, Linux jobs and Windows jobs, each with its own Stop
222	and Start. Stopping Windows jobs leaves Linux jobs running, and the
223	other way round; a kind you stop stays stopped, across restarts, until you
224	start it again. Both are on until you stop one.
225
226	A job still runs only on a runner with every label it names. The app's
227	runner has `self-hosted`, its OS and architecture (`linux` for a runner
228	whose jobs run in containers, whatever the computer is), and `desktop`.
229	It is named after your computer, and a new registration from the same
230	computer takes the place of the old one. Sandboxed, the computer has a
231	runner for each kind of job it can run, named after it with `-linux` or
232	`-windows`: `build-box-linux` has `linux`, and `build-box-windows` has
233	`windows`, on a Windows computer with Windows Sandbox.
234
235	### The runner menu
236
237	The runner's dot, right beside Settings in the title bar, opens its
238	menu, under the dot. The runner's row in the tray opens it too. It shows,
239	live:
240
241	- What the runner is doing, how jobs run, the workspace and the runner's
242	version, with Stop or Start for the whole runner.
243	- When the runner needs you, why, and the fix with its buttons.
244	- Each kind of job, sandboxed: its state, the job it is running with a link
245	to its run, a newer runner waiting for it, why it isn't running and the
246	fix, and its own Stop or Start.
247	- When the app last looked for a newer runner, with **Check for runner
248	updates**.
249	- The last lines of the runner's log, with Open the whole log.
250	- Runner settings…, which opens [the settings](#settings) at Runner.
251
252	Escape, a click outside it, or the dot again closes it. While the window
253	shows no page of g1t's, the dot and the tray open the Runner window
254	instead: the same, in a window of its own.
255
256	### Runner settings
257
258	The settings' Runner section has a card for each kind of job, as the
259	menu has them with more detail (its runner's name on g1t, its version and
260	isolation), and these:
261
262	\| Setting \| Default \| What it does \|
263	\| --- \| --- \| --- \|
264	\| Run jobs on this computer while g1t is open \| On \| Starts the runner a few seconds after the window. Off, nothing runs. \|
265	\| How jobs run \| Sandboxed \| Sandboxed, in Docker, or directly on this computer. See [how jobs run](#how-jobs-run). \|
266	\| 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. \|
267	\| Workspace \| The one you were in when it first registered \| The workspace whose jobs the runner runs. Lists the workspaces you own. \|
268
269	Choosing In Docker or Directly on this computer opens the Runner
270	window, a page that comes with the app, and you choose it there. Jobs
271	outside the sandbox can reach your files, so the app takes that choice
272	only from its own pages, never from a page g1t's server sends; going back
273	to Sandboxed works from either.
274
275	[Seeing it](#seeing-it) says what else it shows.
276
277	### How jobs run
278
279	How jobs run, in [the runner's settings](#runner-settings), decides what a job on your computer can
280	reach. The app never changes it by itself: when the one you chose cannot
281	start, it says why and runs nothing.
282
283	\| Choice \| How \| [Isolation](/guides/self-hosted-runners/#isolation) \| What a job can reach \|
284	\| --- \| --- \| --- \| --- \|
285	\| 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. \|
286	\| 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. \|
287	\| 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. \|
288
289	What the sandbox needs on each computer:
290
291	\| Computer \| Linux jobs \| Windows jobs \|
292	\| --- \| --- \| --- \|
293	\| 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. \|
294	\| macOS 13 or later \| [vfkit](https://github.com/crc-org/vfkit): `brew install vfkit` \| Not released yet \|
295	\| Linux \| Sysbox 0.7 or later in Docker, or QEMU with KVM \| None: Linux jobs are native \|
296
297	The sandbox also needs virtualization turned on in your computer's
298	firmware (Intel VT-x or AMD-V), which most computers have on.
299
300	The sandbox keeps jobs from your computer, not your computer from the
301	sandbox: anything running as your account can look inside it while a job
302	runs. So don't choose Directly on this computer under the same
303	account you use for the sandbox, and don't run software you don't trust
304	there. A runner registered for running jobs directly stays registered when
305	you choose another way, so remove it once you no longer use it:
306	`g1t-runner remove --dir <data folder>/host`, with the data folder below.
307	`g1t-runner sandbox status` warns while one is there. A job's secrets go from inside the sandbox
308	straight to g1t, the job's token left on your computer is spent once the
309	job has started, and the runner's folders are yours alone. [What your
310	computer can see](/guides/self-hosted-runners/#what-your-computer-can-see)
311	has the details.
312
313	For the sandbox, the app runs the same commands you would, with its own
314	copy of `g1t-runner` and its state in the app's local data folder, which
315	never roams to other computers with your profile
316	(`%LOCALAPPDATA%\sh.g1t.desktop\runner` on Windows, or
317	`%APPDATA%\sh.g1t.desktop\runner` where an earlier version set it up;
318	`~/Library/Application Support/sh.g1t.desktop/runner` on macOS;
319	`~/.local/share/sh.g1t.desktop/runner` on Linux):
320
321	\| When \| The app runs \|
322	\| --- \| --- \|
323	\| 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. \|
324	\| Every few seconds while it runs \| `g1t-runner sandbox status --json`, for the tray, the settings and the Runners page. \|
325	\| When g1t quits, or you press Stop running jobs \| `g1t-runner sandbox down`: a job that is running is cut short. \|
326	\| 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. \|
327	\| 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. \|
328	\| 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. \|
329	\| 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. \|
330	\| 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. \|
331	\| 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. \|
332
333	The other two choices run `g1t-runner` from the same data folder, with
334	each one's registration beside it.
335
336	On Windows the sandbox is the WSL distribution `g1t-sandbox`, of which a
337	computer has one. If this copy of g1t has no record of making the one
338	there (you made it with `g1t-runner sandbox up`, or g1t was uninstalled
339	with its data deleted and installed again), the app leaves it alone and
340	says this computer has another sandbox: Remove it and start again
341	removes it, with its VM and registration, and makes the app's own; or keep
342	it and turn the app's runner off. Uninstalling g1t with **Delete the
343	application data** ticked removes the sandbox too.
344
345	### Registering
346
347	The first time, and whenever you change the workspace or how jobs run,
348	the app registers your computer with the workspace. It needs you signed
349	in to g1t in the app as an owner of the workspace, since only owners add
350	runners: the page you are on makes a registration token, which lasts an
351	hour, and hands it to the app, which gives it to the runner once. The
352	token is never shown, and is not kept. From then on the runner starts
353	from its registration, signed in or not.
354
355	The workspace is the one you were in when it first registered; choose
356	another under Workspace in [the runner's settings](#runner-settings). Changing it, or how jobs
357	run, waits for a job that is running to end, then removes the old
358	registration and makes a new one. The sandbox is registered with one
359	workspace, so moving it to another removes it and makes it again, image
360	and all; its old runners stay listed on g1t, offline, until you remove
361	them there.
362
363	### Keeping it up to date
364
365	The app keeps the runner up to date. Soon after it starts, then every
366	hour, it looks for a newer `g1t-runner` in
367	`g1t.sh/downloads/runner/latest.json`, while the runner carries on:
368
369	1. It checks the release is g1t's. The manifest's Ed25519 signature,
370	`latest.json.sig`, must check out against g1t's release key, which is
371	built into the app. A manifest without one, or whose signature
372	doesn't check out, is refused, and nothing in it is used: the app says
373	Update refused: not signed by g1t and keeps the runner it has.
374	2. It downloads the new `g1t-runner` and checks it against the
375	SHA-256 the signed manifest names, throwing away one that differs.
376	3. It puts it in, one kind of job at a time, as each is idle. A job
377	is never cut short for an update. Sandboxed, Linux jobs take the
378	release's image (`g1t-runner sandbox update`, which checks its
379	signature and SHA-256 itself) as soon as they have no job, and
380	Windows jobs, whose runner is `g1t-runner` itself, stop after their
381	job, take the new program and start again, while the other kind runs
382	on. In Docker or directly on this computer, the runner stops between
383	jobs and starts on the new one.
384
385	Meanwhile each card says what is waiting: *0.3.2 ready, installs after
386	this job. Check for runner updates*, in [the runner menu](#the-runner-menu),
387	looks at once, and installs what it finds the same way. An
388	update that fails leaves the runner as it was, and the next hour's look
389	tries again. Turning off Download updates by themselves stops the
390	hourly look; Check for runner updates still looks, and installs.
391
392	### Seeing it
393
394	\| Where \| What it shows \|
395	\| --- \| --- \|
396	\| 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. \|
397	\| 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. \|
398	\| [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…. \|
399	\| [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. \|
400	\| 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. \|
401
402	### When it isn't running
403
404	Each state says why, and how to fix it, in the same words in the tray,
405	the settings and the Runners page.
406
407	\| It says \| Why \| What to do \|
408	\| --- \| --- \| --- \|
409	\| Waiting for jobs \| It is registered and listening. \| Nothing. \|
410	\| Running a job \| It is running that job. \| Nothing; the Runners page links to its run. \|
411	\| Starting, Registering with a workspace, Updating \| It is on its way. \| Wait a few seconds. \|
412	\| Not running: turned off \| Run jobs on this computer while g1t is open is off. \| Turn on. \|
413	\| Not running: stopped \| You pressed Stop running jobs in the tray. \| Start, or open g1t again. \|
414	\| Not running: every kind of job is stopped \| You stopped Linux jobs and Windows jobs, each on its card. \| Start on one. \|
415	\| Linux jobs: Stopped, Windows jobs: Stopped, You stopped them \| You pressed Stop on that card. The other kind runs on. \| Start on the card. \|
416	\| 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. \|
417	\| Not running: signed out \| It isn't registered yet, and registering needs you signed in. \| Sign in, as an owner of the workspace. \|
418	\| 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. \|
419	\| 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. \|
420	\| 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. \|
421	\| 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. \|
422	\| 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. \|
423	\| 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. \|
424	\| 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. \|
425	\| 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. \|
426	\| 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. \|
427	\| 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. \|
428	\| 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. \|
429	\| Not running: the sandbox can't run here \| Something else the sandbox needs, in its own words. \| What it says. \|
430	\| 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. \|
431	\| 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. \|
432	\| 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. \|
433	\| 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. \|
434	\| 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. \|
435	\| 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. \|
436	\| Offline: the server unreachable \| Your computer can't reach g1t. \| Check the connection; it carries on by itself. Retry tries now. \|
437	\| 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. \|
438	\| 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. \|
439	\| 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. \|
440	\| 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. \|
441	\| 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. \|
442	\| 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. \|
443
444	## Links
445
446	A `g1t://` link opens a page in the app: `g1t://acme/-/chat/dm/chn_1`
447	is `g1t.sh/acme/-/chat/dm/chn_1`. The installer registers the scheme; a
448	link opened while the app is running moves it to the page without a
449	reload, and one opened while it is not starts it there. Scripts, launchers
450	and other apps on your computer can use it.
451
452	A link to another site opens in the browser your system uses; the window
453	stays on g1t. That includes this documentation and the status page. So do
454	g1t's own pages for reading about g1t rather than using it: pricing, the
455	policies, security, support and the downloads. Links on g1t that would
456	open a new tab open in the window instead, as it has no tabs. Signing in
457	with GitHub is the one trip outside g1t that stays in the window.
458
459	## Updates
460
461	The app asks `g1t.sh/downloads/desktop/latest.json` for a newer version
462	as it starts and every hour, and downloads one in the background.
463
464	- As it starts, a newer version is installed straight away, and g1t
465	opens again on it a moment later, before you have begun working in it.
466	If something in the app misbehaves, quitting and opening g1t again is
467	enough to be on the newest version. The one exception is your runner
468	in the middle of a job, which is never cut short: then the update waits
469	like any other.
470	- Later on, it never installs under you: a notification and the
471	tray's Restart to update say it is ready, and the restart, or
472	quitting, installs it.
473
474	To see where your copy stands, choose Check for updates… in the Help
475	menu or the tray, or Check for updates in [the settings](#settings).
476	The menu and the tray open the settings at their Updates section,
477	which checks and says the answer there:
478
479	- Up to date. Last checked today at 10:42. You have the newest version.
480	- Version 0.2.0 is downloaded and installs when g1t restarts. A
481	Restart now button beside it installs it and opens the new version,
482	as Restart to update in the Help menu and the tray do.
483	- Could not reach g1t.sh to check. Try again once you are online.
484
485	A check finds and downloads a new version in one go, so the answer can
486	take a moment on a slow connection. The automatic checks and yours are the
487	same check: a version the background found is shown as downloaded when
488	you look. To stop the app checking on its own, turn off
489	Download updates by themselves in [the settings](#settings).
490
491	Every release is signed with g1t's key, whose public half is built into
492	the app; a download whose signature does not check out is thrown away.
493	Because the window shows the site itself, most changes to g1t need no
494	update at all: the app updates when something native changes.
495
496	## Your own g1t
497
498	If you [run g1t yourself](/guides/self-hosting/), point the app at it:
499	Use another g1t… in the tray or the File menu, or Change… in [the
500	settings](#settings), then your server's address, such as
501	`https://g1t.example.com`. The app keeps it and opens there from then on;
502	Use g1t.sh on the same page goes back. Only that server's pages can
503	talk to the app, whichever it is, and updates still come from g1t.sh.
504
505	## What's not there yet
506
507	- Windows jobs on a Mac. Sandboxed macOS jobs are designed, not
508	released, so a Mac's sandbox runs Linux jobs only.
509	- Choosing the sandbox's share of the computer. It takes half the
510	CPUs (at most 8) and a quarter of the memory (2 to 8 GB); the app has no
511	setting for it yet.
512	- Opening the conversation from a notification. Clicking one brings
513	the app forward; the page it is about is coming.
514	- A page of its own while offline. If the network goes away while a
515	page is open, the window shows the web view's own error until it is
516	back; starting without a network shows the app's own page, with a retry.
517	- Notarization on macOS, so the first open needs no right-click.
518	- A phone app. It is being built: see [the phone app](/guides/mobile/).
519
520	## For operators: releasing the app
521
522	The app lives in `apps/desktop` in [g1t's repository](https://g1t.sh/flagon-io/g1t):
523	a Tauri shell in Rust under `src-tauri`, and a launcher page it bundles.
524	A release is a tag `desktop-v<version>`, where the version is the one in
525	`apps/desktop/src-tauri/Cargo.toml`: push it, and the `Desktop release`
526	workflow builds the installers, signs the updater's files, publishes the
527	release to the `g1t-downloads` bucket and points `latest.json` at it.
528	`scripts/desktop-release.mjs` does the same by hand, and its header lists
529	the files a release holds.
530
531	\| What \| Where \|
532	\| --- \| --- \|
533	\| 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. \|
534	\| 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. \|
535	\| Linux builds \| g1t's own Linux machines, in every release. \|
536	\| 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, fetching the MSVC runtime from `aka.ms` and `download.visualstudio.microsoft.com`. \|
537	\| 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`. \|
538	\| 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. \|
539	\| Where releases are served \| `g1t.sh/downloads/desktop/<version>/<file>`, from the same bucket as the runner's and the CLI's releases. \|
540
541	A self-hosted g1t does not serve the app's releases: the app always
542	updates from g1t.sh, and `g1t.sh/download` is where to send people.