Commit ccf220be205f0e509021dbc8cbda90daa638e20d | the-knife

author	Julius Marminge <julius0216@outlook.com> 2026-09-16 01:01:22-07:00
committer	GitHub <noreply@github.com> 2026-09-16 01:01:22-07:00
log	ccf220be205f0e509021dbc8cbda90daa638e20d
tree	aa3d06d2f0e3c061a3830631d0f3734f95c52f14
parent	b900fc94ebe630155783c07324c58af7e6387a03
signature	Signed by PGP key B5690EEEBB952194

docs: make the standalone installer the primary way to get the CLI (#11696)

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

7 files changed, 124 insertions(+), 125 deletions(-)

README.md
apps
- marketing
  - src
    pages
    download.astro
docs
- user

README.md+10-6

...	...	@@ -22,17 +22,21 @@ We wanted something performant, remote-ready, and truly open. If we ever go the
22	22	> - OpenCode: install [OpenCode](https://opencode.ai) and run `opencode auth login`
23	23	> - Antigravity: enable it in Settings, then use Install Antigravity and Sign in with Google. No CLI is required.
24	24
25		### Try it out (install-free)
26
27		The easiest way to test T3 Code is to run the server in your terminal (requires Node.js 22.16+, 23.11+, or 24.10+):
	25	### Command line
28	26
29	27	```bash
30		npx t3@latest
	28	curl -fsSL https://t3.codes/install.sh \| sh
	29	```
	30
	31	On Windows, in PowerShell:
	32
	33	```powershell
	34	irm https://t3.codes/install.ps1 \| iex
31	35	```
32	36
33		This will launch T3 Code's backend on your machine as well as the local web app to control your agents.
	37	Then run `t3` to start the server and open the local web app. `t3 service install` keeps it running in the background, `t3 update` moves to a newer release, and `t3 --help` has the full reference.
34	38
35		Tip: Use `npx t3@latest --help` for the full CLI reference.
	39	To try it once without installing, run `npx t3@latest` instead.
36	40
37	41	### Desktop app
38	42

apps/marketing/src/pages/download.astro+13-8

...	...	@@ -131,10 +131,13 @@ const imageProps = {
131	131	<svg class="platform-icon" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M5 7l5 5-5 5M12 17h7"/></svg>
132	132	<h2 class="platform-name">Terminal</h2>
133	133	</div>
134		<code class="cli-line">npx t3@nightly</code>
135		<p class="cli-note">No Node.js? The preview build installs as a single download:</p>
136		<code class="cli-line">curl -fsSL https://t3.codes/install.sh \| sh</code>
137		<code class="cli-line">irm https://t3.codes/install.ps1 \| iex</code>
	134	<code class="cli-line cli-line--stable">curl -fsSL https://t3.codes/install.sh \| sh</code>
	135	<code class="cli-line cli-line--stable">irm https://t3.codes/install.ps1 \| iex</code>
	136	<code class="cli-line cli-line--nightly">curl -fsSL https://t3.codes/install.sh \| T3CODE_CHANNEL=nightly sh</code>
	137	<code class="cli-line cli-line--nightly">$env:T3CODE_CHANNEL="nightly"; irm https://t3.codes/install.ps1 \| iex</code>
	138	<p class="cli-note">Or try it once without installing:</p>
	139	<code class="cli-line cli-line--stable">npx t3@latest</code>
	140	<code class="cli-line cli-line--nightly">npx t3@nightly</code>
138	141	</section>
139	142	</div>
140	143
...	...	@@ -402,16 +405,18 @@ const imageProps = {
402	405	gap: 0.75rem;
403	406	}
404	407
405		.platform-section--cli {
	408	.download-page[data-channel="nightly"] .platform-section--mobile {
406	409	display: none;
407	410	}
408	411
409		.download-page[data-channel="nightly"] .platform-section--mobile {
	412	/* The CLI ships on both trains; only the install command differs. */
	413	.cli-line--nightly,
	414	.download-page[data-channel="nightly"] .cli-line--stable {
410	415	display: none;
411	416	}
412	417
413		.download-page[data-channel="nightly"] .platform-section--cli {
414		display: flex;
	418	.download-page[data-channel="nightly"] .cli-line--nightly {
	419	display: block;
415	420	}
416	421
417	422	.platform-header {

docs/user/background-service.md+29-54

...	...	@@ -5,65 +5,40 @@ to keep a terminal open.
5	5
6	6	## Manage the service
7	7
8		Run these commands on the machine that will host T3 Code:
	8	Install the `t3` CLI first ([Install T3 Code](./install.md#command-line)), then
	9	run these commands on the machine that will host T3 Code:
9	10
10		\| Task \| Command \|
11		\| ------------------------------- \| --------------------------------- \|
12		\| Install and start \| `npx t3@latest service install` \|
13		\| Inspect status and log location \| `npx t3@latest service status` \|
14		\| Update or repair \| `npx t3@latest service update` \|
15		\| Stop and remove from startup \| `npx t3@latest service uninstall` \|
	11	\| Task \| Command \|
	12	\| ------------------------------- \| ---------------------- \|
	13	\| Install and start \| `t3 service install` \|
	14	\| Inspect status and log location \| `t3 service status` \|
	15	\| Move to a newer release \| `t3 update` \|
	16	\| Restart \| `t3 service restart` \|
	17	\| Stop and remove from startup \| `t3 service uninstall` \|
16	18
17	19	Uninstalling the service leaves your projects, threads, and settings intact.
18
19		Install and update use the version of the CLI you invoke. For nightly, use
20		`npx t3@nightly service update`; replace `nightly` with an exact version to pin
21		one. An older CLI refuses to replace a newer service unless you explicitly add
22		`--allow-downgrade`.
23
24		Updating restarts the server. Finish active work first, and wait for any remote
25		update already in progress. To match a remote client's version, follow
	20	Running `t3 service install` again repairs a service that `t3 service status`
	21	reports as broken.
	22
	23	`t3 update` downloads the newest release on your channel and switches `t3`
	24	and the service to it. Restarting interrupts running agent turns, terminals,
	25	and remote clients, so it asks first; answer no and the service keeps running
	26	the old version until you run `t3 service restart`. Pass `--yes` from a
	27	script. A server you started by hand is left running; stop and start it again
	28	to pick up the new version. Wait for any remote update already in progress
	29	before updating; to match a remote client's version, follow
26	30	[Updating T3 Code](./updating.md).
27	31
28		Self-contained builds install as a download from the T3 Code GitHub release
29		instead of through npm, so the machine running the service does not need
30		Node.js or npm once the CLI is on it. To get the CLI onto a machine without
31		Node, run the install script:
32
33		```sh
34		curl -fsSL https://t3.codes/install.sh \| sh
35		```
	32	Pass an exact version (`t3 update 0.0.42`) to pin one, `--channel nightly` to
	33	switch trains, or `--allow-downgrade` to move backwards. `preview` is a
	34	maintainers' test train: its builds can be broken and are never offered as
	35	updates, so the installer and `t3 update` ask for confirmation before
	36	installing one.
36	37
37		On Windows, run `irm https://t3.codes/install.ps1 \| iex` in PowerShell instead.
38
39		It places `t3` in `~/.local/bin` and reuses the same download when you later
40		run `t3 service install`. It follows the stable train by default; set
41		`T3CODE_CHANNEL=nightly` for nightlies, `T3CODE_VERSION` to pin an exact
42		version, or `T3CODE_RELEASE_BASE_URL` to download from a mirror.
43
44		`preview` is a third train that maintainers cut from unreleased branches to
45		exercise the release pipeline. Those builds can be broken, receive no fixes,
46		and are never offered as updates; the installer and `t3 update` only take you
47		there when you ask for the channel explicitly, and warn you when they do.
48
49		Once a self-contained `t3` is installed, `t3 update` moves the machine to a
50		newer one without npm: it downloads the newest release on the channel the
51		running `t3` came from, verifies it, and points the `t3` launcher at it. When
52		a background service is installed for the same T3 home it asks before
53		restarting it, since a restart interrupts running agent turns, terminals, and
54		remote clients; answer no and the service keeps the old version until you run
55		`t3 service update`. From a script there is no prompt, so pass `--yes` to
56		restart the service. A server you started by hand is never touched; the
57		command tells you it is still on the old version so you can restart it
58		yourself. Pass an exact version (`t3 update 0.0.41-preview.20260912.1595`) to
59		pin one, `--channel` to follow a different release train (moving onto preview from stable or nightly asks for confirmation), or
60		`--allow-downgrade` to move backwards.
61
62		`t3 uninstall` reverses the install script: it shows what it found (the
63		background service, the `t3` launcher, every downloaded version under
64		`~/.t3/runtime`), asks once, and removes them. Your projects, threads, and
65		settings under `~/.t3/userdata` are kept; delete that directory yourself if
66		you want them gone too. Pass `--yes` from a script.
	38	`t3 uninstall` removes the background service, the `t3` launcher, and the
	39	downloaded versions after showing you the list and asking once. Your projects,
	40	threads, and settings under `~/.t3/userdata` are kept. Pass `--yes` from a
	41	script.
67	42
68	43	## Platform support
69	44
...	...	@@ -114,7 +89,7 @@ that session open.
114	89
115	90	On macOS, check System Settings → General → Login Items if the service no
116	91	longer starts at login. If agent work cannot access Desktop, Documents, or
117		Downloads, it may need Full Disk Access for the Node executable listed in
	92	Downloads, it may need Full Disk Access for the `t3` executable listed in
118	93	`ProgramArguments` in
119	94	`~/Library/LaunchAgents/com.t3tools.t3code.service.plist`.
120	95

docs/user/install.md+37-22

...	...	@@ -5,28 +5,44 @@ desktop, web, or mobile app. Set up the machine where the agents will work first
5	5
6	6	## Requirements
7	7
8		`npx t3` needs Node.js only to run npm itself; the CLI it installs is a
9		self-contained executable. SSH hosts and WSL backends need Node.js 22.16+
10		(22.x), 23.11+ (23.x), or 24.10 and later. The native desktop app includes its
11		server runtime.
12
13	8	You need an installed, authenticated provider before starting a thread. You can
14	9	launch T3 Code and configure providers afterwards.
15	10
16		## Run without installing
	11	## Command line
17	12
18	13	```bash
19		npx t3@latest
	14	curl -fsSL https://t3.codes/install.sh \| sh
	15	```
	16
	17	On Windows, in PowerShell:
	18
	19	```powershell
	20	irm https://t3.codes/install.ps1 \| iex
20	21	```
21	22
22		This starts the server and opens the local web app. Run
23		`npx t3@latest --help` for command-line options.
	23	This puts `t3` in `~/.local/bin`. If your shell reports `command not found`
	24	afterwards, that directory is not on your `PATH` yet; the installer prints the
	25	line to add. Set `T3CODE_CHANNEL=nightly` to install the nightly train, or
	26	`T3CODE_VERSION` to pin an exact version.
	27
	28	\| Task \| Command \|
	29	\| ------------------------------------------------ \| --------------------------------------------------------- \|
	30	\| Start the server and open the web app \| `t3` \|
	31	\| Start the server without a browser \| `t3 serve` \|
	32	\| Keep it running in the background (macOS, Linux) \| `t3 service install` ([details](./background-service.md)) \|
	33	\| Move to the newest release \| `t3 update` \|
	34	\| Remove it again \| `t3 uninstall` \|
	35
	36	Run `t3 --help` for the full reference.
	37
	38	To try T3 Code once without installing it, run `npx t3@latest` instead (needs
	39	Node.js for `npx`).
	40
	41	### Intel Macs
24	42
25		The executable is built for Apple Silicon Macs, Linux, and Windows. There is
26		no Intel Mac build of it, because Node cannot produce a single executable for
27		that platform; the Intel desktop app is unaffected. To run a standalone server
28		on an Intel Mac, build it from source. You need Node.js 24 and `vp` (see
29		[Install vp](https://github.com/pingdotgg/t3code#install-vp)):
	43	There is no `t3` executable for Intel Macs (the desktop app is available). To
	44	run a server there, build it from source with Node.js 24 and `vp`
	45	([Install vp](https://github.com/pingdotgg/t3code#install-vp)):
30	46
31	47	```bash
32	48	git clone https://github.com/pingdotgg/t3code
...	...	@@ -34,9 +50,8 @@ cd t3code && vp i && vp run build:desktop
34	50	node apps/server/dist/bin.mjs
35	51	```
36	52
37		A server run this way is a plain Node program: `t3 update` and the background
38		service do not apply, so update it with `git pull` and a rebuild, and start it
39		however you run other Node processes.
	53	`t3 update` and the background service do not apply to a server run this way;
	54	update it with `git pull` and a rebuild.
40	55
41	56	## Desktop app
42	57
...	...	@@ -53,20 +68,20 @@ or use a package manager:
53	68	### Windows Subsystem for Linux
54	69
55	70	Choose a WSL distro in Settings → Connections to run agents and projects
56		there. Install Node.js and provider CLIs inside that distro. T3 Code installs its
57		matching server runtime there automatically; the first launch after an app
58		update can take longer.
	71	there. Install the provider CLIs inside that distro. T3 Code installs its own
	72	server runtime there automatically; the first launch after an app update can
	73	take longer.
59	74
60	75	### Open a project from a terminal
61	76
62	77	With the desktop app already running on the same machine:
63	78
64	79	```bash
65		npx t3 app
	80	t3 app
66	81	```
67	82
68	83	This opens a new thread for the current directory, adding the project if needed.
69		Pass a path, such as `npx t3 app ../my-project`, to open another directory. It requires
	84	Pass a path, such as `t3 app ../my-project`, to open another directory. It requires
70	85	the desktop app, so a standalone server or an SSH session is not enough. If the
71	86	command cannot reach the app, start or update the desktop app and try again.
72	87

docs/user/remote-access.md+15-16

...	...	@@ -12,12 +12,12 @@ Connections, sign in, and enable T3 Connect** for that environment.
12	12	For a command-line host, run:
13	13
14	14	```bash
15		npx t3@latest connect
	15	t3 connect
16	16	```
17	17
18	18	Follow the sign-in instructions. Setup offers a
19	19	[background service](./background-service.md); if you decline it, start the
20		server with `npx t3 serve`. Saving your sign-in alone does not make the machine
	20	server with `t3 serve`. Saving your sign-in alone does not make the machine
21	21	reachable.
22	22
23	23	On your other device, sign in to the same T3 Connect account and choose the
...	...	@@ -42,13 +42,13 @@ For a command-line host, replace `<private-ip>` with the host's LAN or tailnet
42	42	address:
43	43
44	44	```bash
45		npx t3 serve --host <private-ip>
	45	t3 serve --host <private-ip>
46	46	```
47	47
48	48	If a server is already running, generate a fresh link without restarting it:
49	49
50	50	```bash
51		npx t3 pair
	51	t3 pair
52	52	```
53	53
54	54	Scan the QR code on your phone or paste the pairing URL into Add environment
...	...	@@ -88,13 +88,13 @@ HTTPS in Settings → Connections**. Turn it off there to remove that route.
88	88	To start a command-line server with Tailscale HTTPS:
89	89
90	90	```bash
91		npx t3 serve --tailscale-serve
	91	t3 serve --tailscale-serve
92	92	```
93	93
94	94	For an already-running server:
95	95
96	96	```bash
97		npx t3 pair --tailscale
	97	t3 pair --tailscale
98	98	```
99	99
100	100	The pairing link uses an address such as `https://machine.tailnet.ts.net/`.
...	...	@@ -106,7 +106,7 @@ tailscale serve --https=443 off
106	106	```
107	107
108	108	If that port is already in use, choose another with
109		`--tailscale-serve-port`. See `npx t3 pair --help` for other pairing options.
	109	`--tailscale-serve-port`. See `t3 pair --help` for other pairing options.
110	110
111	111	### Hosted web app
112	112
...	...	@@ -125,18 +125,17 @@ In the desktop app, open Settings → Connections → Add environment, choos
125	125	or reuses a server there and opens the port forward for you. Projects, provider
126	126	credentials, and agent work stay on the remote machine.
127	127
128		The remote host needs a compatible [Node.js installation](./install.md#requirements)
129		and [provider setup](./install.md#providers). If launch cannot find Node or reports
130		an incompatible version, check it through a non-interactive SSH session:
	128	The remote host must be Linux or an Apple Silicon Mac with `curl` or `wget`,
	129	`tar`, `sha256sum` or `shasum`, and [provider setup](./install.md#providers).
	130	The first launch downloads T3 Code's server to `~/.t3/runtime` on the host, so
	131	it takes longer than later ones.
	132	Provider CLIs must be on the `PATH` of a non-interactive login shell there;
	133	check with:
131	134
132	135	```bash
133		ssh user@example.com 'sh -lc "command -v node && node --version"'
	136	ssh user@example.com 'sh -lc "command -v claude codex"'
134	137	```
135	138
136		Configure your version manager for non-interactive shells if this differs from
137		your normal terminal. With nvm, setting a compatible default, such as
138		`nvm alias default 24`, can resolve the problem.
139
140	139	If SSH reconnecting fails after an app update, retry the launch once. Removing
141	140	the connection stops a server that T3 Code launched; a server that was already
142	141	running is left alone.
...	...	@@ -149,7 +148,7 @@ For Antigravity's Google callback on a remote host, see
149	148	On the host, Settings → Connections lets authorized administrators create
150	149	pairing links and revoke client sessions. Revoking an unused link prevents new
151	150	pairings; revoke a device's session to remove its existing access. Command-line
152		management is available through `npx t3 auth --help`.
	151	management is available through `t3 auth --help`.
153	152
154	153	A session with an open connection stays listed after its access credential
155	154	expires.

docs/user/updating.md+10-10

...	...	@@ -31,21 +31,21 @@ The offered action depends on how the server runs:
31	31	\| Update the desktop app \| Update the desktop app on the machine running the server, then reopen it if needed. \|
32	32	\| Copy update command \| Stop the command-line server on its host and relaunch with the copied command, keeping your usual startup options. \|
33	33
34		For a background service, run the matching version's CLI on the host:
	34	On the host, run:
35	35
36	36	```sh
37		npx t3@<client-version> service update
	37	t3 update <client-version>
38	38	```
39	39
40		Replace `<client-version>` with the version shown in the notice. Using
41		`@latest` only resolves the mismatch if your client is on that release. An older
42		service launcher may require this local update before it supports remote updates
43		and rollback.
	40	Replace `<client-version>` with the version shown in the notice. The command
	41	asks before restarting the background service; if you decline, run
	42	`t3 service restart` when you are ready. For a server you started by hand,
	43	stop it and start it again afterwards with your usual options such as `--host`
	44	or `--tailscale-serve`.
44	45
45		For a foreground server, the copied command is `npx t3@<client-version>`. Add
46		`serve` if you normally run without a browser, and preserve options such as
47		`--host` or `--tailscale-serve`. See
48		[background services](./background-service.md) for service management.
	46	If you run the server with `npx` rather than an installed `t3`, there is
	47	nothing to update on the host: stop the server and relaunch it as
	48	`npx t3@<client-version>` with the same subcommand and options.
49	49
50	50	## If an update fails
51	51

docs/user/welcome-wizard.md+10-9

...	...	@@ -12,13 +12,14 @@ browser.
12	12
13	13	You can add more computers before continuing:
14	14
15		- T3 Connect connects computers that are signed in to your account. Run
16		`npx t3 connect` on each computer you want to add, then start T3 Code or run
17		`npx t3 serve` so the computer stays available.
	15	- T3 Connect connects computers that are signed in to your account.
	16	[Install the CLI](./install.md#command-line) and run `t3 connect` on each
	17	computer you want to add, then start T3 Code or run `t3 serve` so the
	18	computer stays available.
18	19	- Add a computer connects directly to a server on your network or tailnet.
19		Start the server with `npx t3 serve`, then run `npx t3 pair --tailscale` and
20		paste the pairing link. You can also run `npx t3 serve --host <address>` and
21		use `npx t3 pair` when the server is already reachable on your network.
	20	Start the server with `t3 serve`, then run `t3 pair --tailscale` and paste
	21	the pairing link. You can also run `t3 serve --host <address>` and use
	22	`t3 pair` when the server is already reachable on your network.
22	23
23	24	Saved computers and computers discovered through T3 Connect are selected by
24	25	default. Uncheck any you do not want to set up; this does not disconnect them.
...	...	@@ -36,9 +37,9 @@ unreadable settings with defaults.
36	37
37	38	T3 Code checks each selected computer for Claude Code and Codex. If an agent is
38	39	not installed or signed in, select its action to open a terminal with the
39		correct command ready to run. Install uses the vendor's standalone installer,
40		which does not need Node or npm and keeps Update now working in Settings.
41		Other providers can be enabled in Settings.
	40	correct command ready to run. Install uses the vendor's own installer, which
	41	keeps Update now working in Settings. Other providers can be enabled in
	42	Settings.
42	43
43	44	The setup terminal uses the home directory and environment configured for the
44	45	selected provider instance. Sensitive values remain redacted in Settings and