1# Updating T3 Code
2
3The app you use and the server running your agents can be on different machines.
4When a server is behind your web or desktop app, the update button at the bottom
5of the sidebar and **Settings → Environments** offer to update it.
6
7## Update everything at once
8
9The update button at the bottom of the sidebar updates every connected machine
10in one step. It updates outdated providers, then servers that are behind, then
11the desktop app you are using. Servers move to the
12version your desktop app is installing, or to your web app's version. A
13background service stays on its current release channel. A remote desktop app
14installs the latest release from its own channel. Hover the button to see what
15it will update.
16
17While it runs, the button widens to show progress. It names a machine that is
18taking longer than usual, and offers **Retry** for a server that failed. Click
19it to see every machine. The desktop app restarts once each server has started
20its own restart, after a short countdown. Choose **Later** to keep working and
21restart from the update button when you are ready. A server still restarting
22finishes on its own, and the button keeps showing it after the desktop app
23restarts.
24
25Each server checks that it can install the release before it restarts. If the
26release is not available to a server yet, its update fails, the server keeps
27running, and you can retry. The confirmation lists each machine it skips and
28why, such as a machine that is offline or needs a manual update. Use
29**Settings → Environments** for those.
30
31If a desktop app restarts on its old version, T3 Code tells you the update did
32not apply. It does not install that version again on its own, even when another
33device asks. Use the update button on that machine to retry.
34
35The confirmation counts the running threads that the restarts will interrupt,
36and how many can resume afterwards. See **Continue threads after restarts**
37below.
38
39## Switch between Stable and Nightly
40
41In the desktop app, change **Settings → About → Update track**. T3 Code shows each
42connected machine it will move and each one it skips, then moves them in one
43step. Remote servers install the latest release on the new track. Remote desktop
44apps reinstall on the new track. This app reinstalls last. Your threads,
45settings, and data stay.
46
47A background service cannot move to an older release remotely. When Stable is
48older than its Nightly, run `t3 update --channel stable --allow-downgrade` on
49that machine.
50
51A switch is blocked for a machine whose database already has changes the
52target release does not support, or when T3 Code cannot confirm that it does.
53The dialog says why: update a machine on its current track first when its
54release is too old to check, or wait until the target track includes the
55changes. A Mac running the desktop app must switch on that Mac.
56
57Each machine keeps the new track even if its switch did not finish, but it
58moves to that track only through a switch. **Update track** shows how many
59machines still run the other track. **Review** opens the same dialog with fresh
60checks.
61
62## Before you update
63
64Server updates restart the connection and can interrupt active agents and
65terminal commands. Saved threads, settings, and project files remain.
66
67**Settings → Maintenance → Continue threads after restarts** is on by default.
68It resumes supported active threads after an update, crash, or machine
69restart. Changes are saved to connected environments that support this setting;
70update older servers first. If a supported environment was offline or has a
71different value, use **Apply to all** in Settings after it connects.
72T3 Code must start again on that machine;
73the setting does not enable automatic startup. Terminal commands may still be
74interrupted, and threads without saved provider resume state need a new message.
75A thread that finished its turn to wait on a subagent, a background task, or a
76command or monitor the agent said it was waiting on is woken and told that this work
77stopped. Other background shells and monitors, such as a dev server and its
78watchdog, do not wake it; the thread learns about them with your next message.
79A thread is not resumed while it waits for your approval, answer, or secret, or
80while it is archived, snoozed, or settled. After three automatic resumes in a row,
81the thread waits for your next message.
82
83Updates from the previous orchestration system preserve conversation transcripts but cannot carry
84every kind of runtime history forward. Read [Threads from older T3 Code versions](./thread-migration.md)
85before continuing an important older thread.
86
87## When versions don't match
88
89A client and server must speak the same orchestration protocol. If they do not, the connection is
90refused rather than running half-upgraded:
91
92An app newer than the server is blocked before connecting, with a notice telling you to update
93 T3 Code on the machine named in the notice.
94A server newer than your app refuses the connection with an update message.
95
96Update the side the notice names, then reconnect.
97
98## Update a connected server
99
100The offered action depends on how the server runs:
101
102| Action | What to do |
103| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
104| **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. |
105| **Update the desktop app** | Update the desktop app on the machine running the server, then reopen it if needed. |
106| **Copy update command** | Run the command on the named host to update the detected global npm install or installed `t3` command, then restart the server with your usual options. |
107| **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. |
108
109On the host, run:
110
112t3 update <client-version>
114
115Replace `<client-version>` with the version shown in the notice. The command
116asks before restarting the background service; if you decline, run
117`t3 service restart` when you are ready. For a server you started by hand,
118stop it and start it again afterwards with your usual options such as `--host`
119or `--tailscale-serve`.
120
121If you decline the restart for a background service installed by an older
122release, the service can stay down after a crash or reboot until you run
123`t3 service restart`.
124
125If you run the server with `npx` rather than an installed `t3`, there is
126nothing to update on the host: stop the server and relaunch it as
127`npx t3@<client-version>` with the same subcommand and options.
128
129## If an update fails
130
131Keep the client open until it reconnects or reports a failure. A failed service
132update can roll back to the previous version. If the update still fails:
133
134Retry the offered action once.
135Check that you updated the server's machine, not only the device you are using.
136For a command-line server, stop it and relaunch the exact version shown in the notice.
137
138Only one server can use a T3 home directory at a time. If startup reports that
139another server owns it, stop that server before retrying, or use a separate home
140directory and pair with the running server.
141
142### macOS app does not reopen after an Alpha update
143
144Updating an older **T3 Code (Alpha)** installation can replace it with
145**T3 Code (Beta)** without reopening the app. Open **T3 Code (Beta)** from
146Applications, or run:
147
149open "/Applications/T3 Code (Beta).app"
151
152If an old Dock shortcut no longer opens the app, remove it and add the Beta app
153from Applications again.
154
155## If the desktop app does not start
156
157If the desktop app's server keeps failing at startup, T3 Code shows a "T3 Code
158could not start" window instead of the app. If a newer version is available,
159choose **Update** to install it. If not, the window links to the last version
160that started on your computer. Download and install it to go back. Use **Copy
161details** to include the error in a bug report.
162
163## Registries and proxies
164
165Each server checks T3 Code releases, and providers installed with npm, through
166its own npm, so the checks use npm's configured registry, authentication, and
167proxy settings. Providers installed with Homebrew or pnpm check through those
168tools.
169Configure npm on the server's machine. If that registry cannot be reached, the
170release shows as unavailable; T3 Code does not try the public registry instead.
171Machines without npm check the public npm registry directly.
172
173## Update providers
174
175**Settings → Providers** shows provider updates for the selected environment.
176**Update all** updates every outdated provider on every connected environment
177at once. Hover it to see which providers it will update. A provider is left out
178when any of its enabled, outdated instances offers only a manual update command,
179or when its instances use different update commands, such as two instances that
180run different CLI installs. Update those by hand, or point every instance of the
181provider at the same CLI.
182
183After a successful provider CLI update, T3 Code refreshes model discovery for
184every enabled instance of that provider using its own configuration. Connected
185clients receive the refreshed catalogs automatically. Provider update checks
186must be enabled to download the latest T3 Code model catalog.
187
188Provider updates do not restart running chats. An existing session can keep
189using the previous CLI until it ends. If discovery fails, check the provider
190status and refresh it again.
191
192## Mobile updates
193
194To update an environment from your phone, open **Settings → Environments** and
195select it. **Check for updates** finds the latest release on that environment's
196current release channel. Keep the app open while the environment updates and
197reconnects. Hosts that cannot update remotely show instructions for updating on
198the machine instead.
199
200The same page lets you refresh provider status and update supported providers.
201These controls require a connected environment and permission to operate it.
202Provider update checks and restart continuation preferences are in
203**Settings → Maintenance**. If provider update checks are disabled, enable them
204there before refreshing to find newer versions. The same setting controls whether
205T3 Code downloads model catalog updates, so with it off new models may not appear
206until you enable it and refresh provider status.
207
208Install App Store or Google Play releases as usual. The mobile app can also
209download updates in the background and apply them when you next leave the app.
210It saves drafts and queued messages before restarting. If you keep the app open
211for a long time, it may ask to install immediately; choosing **Later** leaves the
212update queued for the next suitable moment.