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

Commit

The docs describe the desktop app's runner. The desktop guide has a section of its own: it starts with the app and stops when g1t quits, Stop and Start in the settings and the tray, its labels and name; how jobs run, sandboxed by default (nested-container, the runner's image under Sysbox on Linux, and a sandbox for Windows and macOS that is not released yet), in Docker (container, not a sandbox, since the runner controls the computer's Docker), or directly on the computer (host, everything your account can reach); registering through the site as an owner, with the token never shown; how the app keeps the runner up to date while it is idle; where to see it, in the tray, the settings and the Runners page's Desktops; and a table of every state the runner can be in, with why and what to do. The self-hosted runners guide says where the desktop app's choices sit in its isolation table and lists Desktops on the Runners page, and the features page no longer calls the runner in the desktop app coming.

syntaqxcommitted 2d agoParent8555558Browse files

1	1		---
2	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, and updates that install themselves.
	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	4		---
5	5
6	6		The desktop app is g1t in a window of its own. Everything in it is the
⋯
17	17		- Updates that install themselves, signed by g1t, in the background.
18	18		- Your own g1t, if you [run one](/guides/self-hosting/): the app points
19	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).
20	23		- Settings of its own: opening when you sign in to your computer,
21		−	what closing the window does, notifications, the badge, zoom and updates.
	24	+	what closing the window does, notifications, the badge, zoom, updates
	25	+	and the runner.
22	26
23	27		Get it at [g1t.sh/download](https://g1t.sh/download), or from your account
24	28		menu, Get the desktop app.
⋯
132	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. \|
133	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. \|
134	138		\| Zoom \| 100% \| How large g1t is drawn, from 67% to 200%. The View menu changes it too. \|
135		−	\| Download updates by themselves \| On \| Off, the app never checks on its own; Check for updates still does. \|
	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. \|
136	143
137	144		The settings window also shows the app's version and whether it is up to
138	145		date, with Check for updates (see [Updates](#updates)), and the server it opens, with Change… to [use another
139	146		g1t](#your-own-g1t).
140	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	+
141	254		## Links
142	255
143	256		A `g1t://` link opens a page in the app: `g1t://acme/-/chat/dm/chn_1`
⋯
194	307
195	308		## What's not there yet
196	309
197		−	- A runner inside the app, so an agent can work on your own machine
198		−	with what only it reaches, as [the runners page](/guides/self-hosted-runners/)
199		−	says. The self-hosted runner works on the same machine meanwhile.
	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).
200	315		- Opening the conversation from a notification. Clicking one brings
201	316		the app forward; the page it is about is coming.
202	317		- A page of its own while offline. If the network goes away while a

96	96
97	97		\| Isolation \| How you get it \| What a job can reach \|
98	98		\| --- \| --- \| --- \|
99		−	\| `nested-container` \| The runner's image under Sysbox, as above. \| Its own container, and its own Docker Engine if it uses Docker. Not the machine, and not other jobs. \|
100		−	\| `container` \| `g1t-runner` installed on the machine with Docker, or the image given the machine's Docker socket with the override. \| Its own container. The runner itself drives the machine's Docker, which can do anything on the machine, so a job that escapes its container, or anything that takes over the runner, controls the machine. \|
101		−	\| `host` \| `--no-docker`. Deprecated. \| Everything the runner's user can: the machine, its files, and what earlier jobs left. \|
	99	+	\| `nested-container` \| The runner's image under Sysbox, as above, or [the desktop app](/guides/desktop/#how-jobs-run)'s Sandboxed choice. \| Its own container, and its own Docker Engine if it uses Docker. Not the machine, and not other jobs. \|
	100	+	\| `container` \| `g1t-runner` installed on the machine with Docker, the desktop app's In Docker choice, or the image given the machine's Docker socket with the override. \| Its own container. The runner itself drives the machine's Docker, which can do anything on the machine, so a job that escapes its container, or anything that takes over the runner, controls the machine. \|
	101	+	\| `host` \| `--no-docker`, or the desktop app's Directly on this computer choice. Deprecated. \| Everything the runner's user can: the machine, its files, and what earlier jobs left. \|
102	102
103	103		### What a job's container gets
104	104
⋯
201	201		[a computer of its own](/guides/agents/#its-computer) on g1t cloud, whose
202	202		home stays between sessions and which sleeps when idle; the page says so
203	203		under Agents' computers and more. Pinning an agent's computer to one of
204		−	your own runners, a runner in the desktop app, and an official agent image
205		−	are coming, and the page labels them so.
	204	+	your own runners and an official agent image are coming, and the page
	205	+	labels them so.
	206	+
	207	+	Desktops lists every computer in the workspace with [the desktop
	208	+	app](/guides/desktop/#the-runner), whose runner runs while g1t is open
	209	+	there: what each is doing, or why it isn't running and how to fix it, in
	210	+	the app's own words, and how it runs jobs. A computer whose g1t has been
	211	+	closed for ten minutes says g1t is closed on its name, and so does its
	212	+	runner in the list, rather than Offline.
	213	+
	214	+	## A runner in the desktop app
	215	+
	216	+	[The desktop app](/guides/desktop/#the-runner) runs a runner for you
	217	+	while it is open, with nothing to install or register: it registers your
	218	+	computer with the workspace you choose, as you, through the site, and
	219	+	keeps the runner up to date. It runs jobs sandboxed by default
	220	+	(`nested-container`); running them in Docker (`container`) or directly
	221	+	on the computer (`host`) are settings you choose, and the app never falls
	222	+	back to them. Its runner has the label `desktop` besides the usual ones.
206	223
207	224		## Add a runner
208	225

70	70		\| Scratchpads \| Tools, reports and agents anyone can build on a copy of the data, used in production only after review. \| <Status is="coming" /> \|
71	71		\| [The desktop app](/guides/desktop/) \| g1t in a window of its own for Windows, macOS and Linux, with notifications from your system. \| <Status is="preview" /> \|
72	72		\| [The phone app](/guides/mobile/) \| Chat with your team and its agents, live, with notifications on the phone; review pull requests. Android first, for g1t.sh or your own g1t; not in the stores yet. \| <Status is="preview" /> \|
73		−	\| A runner inside the desktop app \| Agents working on your own machine, with what only it reaches. \| <Status is="coming" /> \|
	73	+	\| [A runner in the desktop app](/guides/desktop/#the-runner) \| Your workspace's self-hosted jobs on your computer while g1t is open, registered and kept up to date by the app, sandboxed by default. The sandbox on Windows and macOS is coming; until then jobs there run in Docker or on the computer, if you choose. \| <Status is="preview" /> \|
74	74
75	75		## Agents
76	76

flagon-io/g1t

Comments