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
 > - OpenCode: install [OpenCode](https://opencode.ai) and run `opencode auth login`
 > - Antigravity: enable it in Settings, then use **Install Antigravity** and **Sign in with Google**. No CLI is required.
-### Try it out (install-free)
+### Command line
-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+):
 ```bash
-npx t3@latest
+curl -fsSL https://t3.codes/install.sh | sh
+```
+On Windows, in PowerShell:
+```powershell
+irm https://t3.codes/install.ps1 | iex
 ```
-This will launch T3 Code's backend on your machine as well as the local web app to control your agents.
+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.
-Tip: Use `npx t3@latest --help` for the full CLI reference.
+To try it once without installing, run `npx t3@latest` instead.
 ### Desktop app

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

 @@ -131,10 +131,13 @@ const imageProps = {
           <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>
           <h2 class="platform-name">Terminal</h2>
         </div>
-        <code class="cli-line">npx t3@nightly</code>
+        <code class="cli-line cli-line--stable">curl -fsSL https://t3.codes/install.sh | sh</code>
-        <p class="cli-note">No Node.js? The preview build installs as a single download:</p>
+        <code class="cli-line cli-line--stable">irm https://t3.codes/install.ps1 | iex</code>
-        <code class="cli-line">curl -fsSL https://t3.codes/install.sh | sh</code>
+        <code class="cli-line cli-line--nightly">curl -fsSL https://t3.codes/install.sh | T3CODE_CHANNEL=nightly sh</code>
-        <code class="cli-line">irm https://t3.codes/install.ps1 | iex</code>
+        <code class="cli-line cli-line--nightly">$env:T3CODE_CHANNEL="nightly"; irm https://t3.codes/install.ps1 | iex</code>
+        <p class="cli-note">Or try it once without installing:</p>
+        <code class="cli-line cli-line--stable">npx t3@latest</code>
+        <code class="cli-line cli-line--nightly">npx t3@nightly</code>
       </section>
     </div>
 @@ -402,16 +405,18 @@ const imageProps = {
     gap: 0.75rem;
   }
-  .platform-section--cli {
+  .download-page[data-channel="nightly"] .platform-section--mobile {
     display: none;
   }
-  .download-page[data-channel="nightly"] .platform-section--mobile {
+  /* The CLI ships on both trains; only the install command differs. */
+  .cli-line--nightly,
+  .download-page[data-channel="nightly"] .cli-line--stable {
     display: none;
   }
-  .download-page[data-channel="nightly"] .platform-section--cli {
+  .download-page[data-channel="nightly"] .cli-line--nightly {
-    display: flex;
+    display: block;
   }
   .platform-header {

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

...	@@ -5,65 +5,40 @@ to keep a terminal open.	...	@@ -5,65 +5,40 @@ to keep a terminal open.
5		5
6	## Manage the service	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	\| Task \| Command \|
11	\| ------------------------------- \| --------------------------------- \|	12	\| ------------------------------- \| ---------------------- \|
12	\| Install and start \| `npx t3@latest service install` \|	13	\| Install and start \| `t3 service install` \|
13	\| Inspect status and log location \| `npx t3@latest service status` \|	14	\| Inspect status and log location \| `t3 service status` \|
14	\| Update or repair \| `npx t3@latest service update` \|	15	\| Move to a newer release \| `t3 update` \|
15	\| Stop and remove from startup \| `npx t3@latest service uninstall` \|	16	\| Restart \| `t3 service restart` \|
		17	\| Stop and remove from startup \| `t3 service uninstall` \|
16		18
17	Uninstalling the service leaves your projects, threads, and settings intact.	19	Uninstalling the service leaves your projects, threads, and settings intact.
18		20	Running `t3 service install` again repairs a service that `t3 service status`
19	Install and update use the version of the CLI you invoke. For nightly, use	21	reports as broken.
20	`npx t3@nightly service update`; replace `nightly` with an exact version to pin	22
21	one. An older CLI refuses to replace a newer service unless you explicitly add	23	`t3 update` downloads the newest release on your channel and switches `t3`
22	`--allow-downgrade`.	24	and the service to it. Restarting interrupts running agent turns, terminals,
23		25	and remote clients, so it asks first; answer no and the service keeps running
24	Updating restarts the server. Finish active work first, and wait for any remote	26	the old version until you run `t3 service restart`. Pass `--yes` from a
25	update already in progress. To match a remote client's version, follow	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	[Updating T3 Code](./updating.md).	30	[Updating T3 Code](./updating.md).
27		31
28	Self-contained builds install as a download from the T3 Code GitHub release	32	Pass an exact version (`t3 update 0.0.42`) to pin one, `--channel nightly` to
29	instead of through npm, so the machine running the service does not need	33	switch trains, or `--allow-downgrade` to move backwards. `preview` is a
30	Node.js or npm once the CLI is on it. To get the CLI onto a machine without	34	maintainers' test train: its builds can be broken and are never offered as
31	Node, run the install script:	35	updates, so the installer and `t3 update` ask for confirmation before
32		36	installing one.
33	```sh
34	curl -fsSL https://t3.codes/install.sh \| sh
35	```
36		37
37	On Windows, run `irm https://t3.codes/install.ps1 \| iex` in PowerShell instead.	38	`t3 uninstall` removes the background service, the `t3` launcher, and the
38		39	downloaded versions after showing you the list and asking once. Your projects,
39	It places `t3` in `~/.local/bin` and reuses the same download when you later	40	threads, and settings under `~/.t3/userdata` are kept. Pass `--yes` from a
40	run `t3 service install`. It follows the stable train by default; set	41	script.
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.
67		42
68	## Platform support	43	## Platform support
69		44
...	@@ -114,7 +89,7 @@ that session open.	...	@@ -114,7 +89,7 @@ that session open.
114		89
115	On macOS, check System Settings → General → Login Items if the service no	90	On macOS, check System Settings → General → Login Items if the service no
116	longer starts at login. If agent work cannot access Desktop, Documents, or	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	`ProgramArguments` in	93	`ProgramArguments` in
119	`~/Library/LaunchAgents/com.t3tools.t3code.service.plist`.	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,28 +5,44 @@ desktop, web, or mobile app. Set up the machine where the agents will work first
5		5
6	## Requirements	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	You need an installed, authenticated provider before starting a thread. You can	8	You need an installed, authenticated provider before starting a thread. You can
14	launch T3 Code and configure providers afterwards.	9	launch T3 Code and configure providers afterwards.
15		10
16	## Run without installing	11	## Command line
17		12
18	```bash	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	This puts `t3` in `~/.local/bin`. If your shell reports `command not found`
23	`npx t3@latest --help` for command-line options.	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	43	There is no `t3` executable for Intel Macs (the desktop app is available). To
26	no Intel Mac build of it, because Node cannot produce a single executable for	44	run a server there, build it from source with Node.js 24 and `vp`
27	that platform; the Intel desktop app is unaffected. To run a standalone server	45	([Install vp](https://github.com/pingdotgg/t3code#install-vp)):
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)):
30		46
31	```bash	47	```bash
32	git clone https://github.com/pingdotgg/t3code	48	git clone https://github.com/pingdotgg/t3code
...	@@ -34,9 +50,8 @@ cd t3code && vp i && vp run build:desktop	...	@@ -34,9 +50,8 @@ cd t3code && vp i && vp run build:desktop
34	node apps/server/dist/bin.mjs	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	53	`t3 update` and the background service do not apply to a server run this way;
38	service do not apply, so update it with `git pull` and a rebuild, and start it	54	update it with `git pull` and a rebuild.
39	however you run other Node processes.
40		55
41	## Desktop app	56	## Desktop app
42		57
...	@@ -53,20 +68,20 @@ or use a package manager:	...	@@ -53,20 +68,20 @@ or use a package manager:
53	### Windows Subsystem for Linux	68	### Windows Subsystem for Linux
54		69
55	Choose a WSL distro in Settings → Connections to run agents and projects	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	71	there. Install the provider CLIs inside that distro. T3 Code installs its own
57	matching server runtime there automatically; the first launch after an app	72	server runtime there automatically; the first launch after an app update can
58	update can take longer.	73	take longer.
59		74
60	### Open a project from a terminal	75	### Open a project from a terminal
61		76
62	With the desktop app already running on the same machine:	77	With the desktop app already running on the same machine:
63		78
64	```bash	79	```bash
65	npx t3 app	80	t3 app
66	```	81	```
67		82
68	This opens a new thread for the current directory, adding the project if needed.	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	the desktop app, so a standalone server or an SSH session is not enough. If the	85	the desktop app, so a standalone server or an SSH session is not enough. If the
71	command cannot reach the app, start or update the desktop app and try again.	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 +12,12 @@ Connections, sign in, and enable T3 Connect** for that environment.
12	For a command-line host, run:	12	For a command-line host, run:
13		13
14	```bash	14	```bash
15	npx t3@latest connect	15	t3 connect
16	```	16	```
17		17
18	Follow the sign-in instructions. Setup offers a	18	Follow the sign-in instructions. Setup offers a
19	[background service](./background-service.md); if you decline it, start the	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	reachable.	21	reachable.
22		22
23	On your other device, sign in to the same T3 Connect account and choose the	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,13 +42,13 @@ For a command-line host, replace `<private-ip>` with the host's LAN or tailnet
42	address:	42	address:
43		43
44	```bash	44	```bash
45	npx t3 serve --host <private-ip>	45	t3 serve --host <private-ip>
46	```	46	```
47		47
48	If a server is already running, generate a fresh link without restarting it:	48	If a server is already running, generate a fresh link without restarting it:
49		49
50	```bash	50	```bash
51	npx t3 pair	51	t3 pair
52	```	52	```
53		53
54	Scan the QR code on your phone or paste the pairing URL into Add environment	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,13 +88,13 @@ HTTPS in Settings → Connections**. Turn it off there to remove that route.
88	To start a command-line server with Tailscale HTTPS:	88	To start a command-line server with Tailscale HTTPS:
89		89
90	```bash	90	```bash
91	npx t3 serve --tailscale-serve	91	t3 serve --tailscale-serve
92	```	92	```
93		93
94	For an already-running server:	94	For an already-running server:
95		95
96	```bash	96	```bash
97	npx t3 pair --tailscale	97	t3 pair --tailscale
98	```	98	```
99		99
100	The pairing link uses an address such as `https://machine.tailnet.ts.net/`.	100	The pairing link uses an address such as `https://machine.tailnet.ts.net/`.
...	@@ -106,7 +106,7 @@ tailscale serve --https=443 off	...	@@ -106,7 +106,7 @@ tailscale serve --https=443 off
106	```	106	```
107		107
108	If that port is already in use, choose another with	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	### Hosted web app	111	### Hosted web app
112		112
...	@@ -125,18 +125,17 @@ In the desktop app, open Settings → Connections → Add environment, choos	...	@@ -125,18 +125,17 @@ In the desktop app, open Settings → Connections → Add environment, choos
125	or reuses a server there and opens the port forward for you. Projects, provider	125	or reuses a server there and opens the port forward for you. Projects, provider
126	credentials, and agent work stay on the remote machine.	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)	128	The remote host must be Linux or an Apple Silicon Mac with `curl` or `wget`,
129	and [provider setup](./install.md#providers). If launch cannot find Node or reports	129	`tar`, `sha256sum` or `shasum`, and [provider setup](./install.md#providers).
130	an incompatible version, check it through a non-interactive SSH session:	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	```bash	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	If SSH reconnecting fails after an app update, retry the launch once. Removing	139	If SSH reconnecting fails after an app update, retry the launch once. Removing
141	the connection stops a server that T3 Code launched; a server that was already	140	the connection stops a server that T3 Code launched; a server that was already
142	running is left alone.	141	running is left alone.
...	@@ -149,7 +148,7 @@ For Antigravity's Google callback on a remote host, see	...	@@ -149,7 +148,7 @@ For Antigravity's Google callback on a remote host, see
149	On the host, Settings → Connections lets authorized administrators create	148	On the host, Settings → Connections lets authorized administrators create
150	pairing links and revoke client sessions. Revoking an unused link prevents new	149	pairing links and revoke client sessions. Revoking an unused link prevents new
151	pairings; revoke a device's session to remove its existing access. Command-line	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	A session with an open connection stays listed after its access credential	153	A session with an open connection stays listed after its access credential
155	expires.	154	expires.

docs/user/updating.md+10-10

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

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

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