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