clover's git

the-knife

1	# Updating T3 Code
2
3	The app you use and the server running your agents can be on different machines.
4	When a server is behind your web or desktop app, an update notice appears in the
5	conversation and **Settings → Connections**. Update the machine named in that
6	notice.
7
8	## Update everything at once
9
10	The update button at the bottom of the sidebar updates every connected machine
11	in one step. It updates outdated providers, then servers that are behind, then
12	the desktop app you are using, which restarts last. Servers move to the
13	version your desktop app is installing, or to your web app's version. A
14	background service stays on its current release channel. A remote desktop app
15	installs the latest release from its own channel. Hover the button to see what
16	it will update.
17
18	Server updates appear only after that version is published to npm. Remote
19	desktop apps do not wait for npm. The confirmation lists each machine it skips
20	and why, such as a machine that is offline or needs a manual update. Use the
21	notice or **Settings → Connections** for those.
22
23	If a desktop app restarts on its old version, T3 Code tells you the update did
24	not apply. It does not install that version again on its own, even when another
25	device asks. Use the update button on that machine to retry.
26
27	The confirmation counts the running threads that the restarts will interrupt,
28	and how many can resume afterwards. See **Continue threads after restarts**
29	below.
30
31	## Before you update
32
33	Server updates restart the connection and can interrupt active agents and
34	terminal commands. Saved threads, settings, and project files remain.
35
36	**Settings → General → Continue threads after restarts** is on by default.
37	It resumes supported active threads after an update, crash, or machine
38	restart. Changes are saved to connected environments that support this setting;
39	update older servers first. If a supported environment was offline or has a
40	different value, use **Apply to all** in Settings after it connects.
41	T3 Code must start again on that machine;
42	the setting does not enable automatic startup. Terminal commands may still be
43	interrupted, and threads without saved provider resume state need a new message.
44	A thread that finished its turn to wait on a monitor, subagent, or background task
45	is woken and told that this work stopped. A background shell, such as a dev server,
46	does not wake it; the thread learns about it with your next message.
47	A thread is not resumed while it waits for your approval, answer, or secret, or
48	while it is archived, snoozed, or settled. After three automatic resumes in a row,
49	the thread waits for your next message.
50
51	Updates from the previous orchestration system preserve conversation transcripts but cannot carry
52	every kind of runtime history forward. Read [Threads from older T3 Code versions](./thread-migration.md)
53	before continuing an important older thread.
54
55	## When versions don't match
56
57	A client and server must speak the same orchestration protocol. If they do not, the connection is
58	refused rather than running half-upgraded:
59
60	- An app newer than the server is blocked before connecting, with a notice telling you to update
61	T3 Code on the machine named in the notice.
62	- A server newer than your app refuses the connection with an update message.
63
64	Update the side the notice names, then reconnect.
65
66	## Update a connected server
67
68	The offered action depends on how the server runs:
69
70	| Action | What to do |
71	| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
72	| **Update server** | Keep the client open while it installs and reconnects. Supported background services update remotely. For a desktop-hosted server, this also closes and relaunches the desktop app on the host. |
73	| **Update the desktop app** | Update the desktop app on the machine running the server, then reopen it if needed. |
74	| **Copy update command** | Run the command on the named host to update the detected global npm install, then restart the server with your usual options. |
75	| **Copy relaunch command** | Stop the command-line server on its host and relaunch with the copied command, keeping your usual subcommand and options. This does not update an installed `t3` command. |
76
77	On the host, run:
78
79	```sh
80	t3 update <client-version>
81	```
82
83	Replace `<client-version>` with the version shown in the notice. The command
84	asks before restarting the background service; if you decline, run
85	`t3 service restart` when you are ready. For a server you started by hand,
86	stop it and start it again afterwards with your usual options such as `--host`
87	or `--tailscale-serve`.
88
89	If you run the server with `npx` rather than an installed `t3`, there is
90	nothing to update on the host: stop the server and relaunch it as
91	`npx t3@<client-version>` with the same subcommand and options.
92
93	## If an update fails
94
95	Keep the client open until it reconnects or reports a failure. A failed service
96	update can roll back to the previous version. If the update still fails:
97
98	1. Retry the offered action once.
99	2. Check that you updated the server's machine, not only the device you are using.
100	3. For a command-line server, stop it and relaunch the exact version shown in the notice.
101
102	Only one server can use a T3 home directory at a time. If startup reports that
103	another server owns it, stop that server before retrying, or use a separate home
104	directory and pair with the running server.
105
106	## Update providers
107
108	**Settings → Providers** shows provider updates for the selected environment.
109	**Update all** updates every outdated provider on every connected environment
110	at once. Hover it to see which providers it will update. Providers that only
111	offer a manual update command are not included.
112
113	## Mobile updates
114
115	To update an environment from your phone, open **Settings → Environments** and
116	select it. **Check for updates** finds the latest release on that environment's
117	current release channel. Keep the app open while the environment updates and
118	reconnects. Hosts that cannot update remotely show instructions for updating on
119	the machine instead.
120
121	The same page lets you refresh provider status and update supported providers.
122	These controls require a connected environment and permission to operate it.
123	Provider update checks and restart continuation preferences are in
124	**Settings → Maintenance**. If provider update checks are disabled, enable them
125	there before refreshing to find newer versions. The same setting controls whether
126	T3 Code downloads model catalog updates, so with it off new models may not appear
127	until you enable it and refresh provider status.
128
129	Install App Store or Google Play releases as usual. The mobile app can also
130	download updates in the background and apply them when you next leave the app.
131	It saves drafts and queued messages before restarting. If you keep the app open
132	for a long time, it may ask to install immediately; choosing **Later** leaves the
133	update queued for the next suitable moment.