Showing the changes to docs (2 of 12 files). Show all
Unified · Split
| @@ -32,17 +32,17 @@ the mismatch and action disappear. · 31 unmodified lines | ||
| 32 | 32 | |
| 33 | 33 | The server resolves its capability once at startup and publishes it in the environment descriptor. |
| 34 | 34 | |
| 35 | −| Advertised value | Process shape | Client behavior | | |
| 36 | −| ----------------- | --------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | | |
| 37 | −| `boot-service` | Linux server running under the T3-managed systemd user service | Call the update RPC; the service unit is replaced and restarted. | | |
| 38 | −| `respawn` | Published npm CLI running in the foreground on macOS or Linux | Call the update RPC; the process hands off to a detached replacement. | | |
| 39 | −| `desktop-managed` | Backend supervised by the desktop app | Tell the user to update the desktop app on the server machine. | | |
| 40 | −| absent | Older server, development checkout, Windows foreground process, or an unrecognized supervisor | Offer the exact manual relaunch command. | | |
| 35 | +| Advertised value | Process shape | Client behavior | | |
| 36 | +| ----------------- | --------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | | |
| 37 | +| `boot-service` | Server running under the T3-managed systemd user service or macOS LaunchAgent | Call the update RPC; the managed service switches runtime and restarts. | | |
| 38 | +| `respawn` | Published npm CLI running in the foreground on macOS or Linux | Call the update RPC; the process hands off to a detached replacement. | | |
| 39 | +| `desktop-managed` | Backend supervised by the desktop app | Tell the user to update the desktop app on the server machine. | | |
| 40 | +| absent | Older server, development checkout, Windows foreground process, or an unrecognized supervisor | Offer the exact manual relaunch command. | | |
| 41 | 41 | |
| 42 | 42 | Desktop ownership takes precedence over process-shape detection. A desktop-managed backend must |
| 43 | 43 | never spawn a second CLI server beside the app-owned process. Likewise, a process launched by an |
| 44 | −unrecognized systemd unit does not claim the foreground respawn path because its supervisor could | |
| 45 | −bring the old version back. | |
| 44 | +unrecognized systemd unit or marked LaunchAgent does not claim the foreground respawn path because | |
| 45 | +its supervisor could bring the old version back. | |
| 46 | 46 | |
| 47 | 47 | ## Update Flow |
| 48 | 48 | |
| @@ -56,7 +56,7 @@ flowchart TD · 7 unmodified lines | ||
| 56 | 56 | F --> G[Run version preflight] |
| 57 | 57 | G -->|fails| H[Remove failed runtime and keep current server] |
| 58 | 58 | G -->|passes| I{Handoff method} |
| 59 | − I -->|boot-service| J[Rewrite and restart T3 systemd unit] | |
| 59 | + I -->|boot-service| J[Switch runtime and restart managed service] | |
| 60 | 60 | I -->|respawn| K[Start delayed replacement and exit current process] |
| 61 | 61 | J --> L[Client reconnects] |
| 62 | 62 | K --> L |
| @@ -77,10 +77,11 @@ preflight also removes the candidate runtime so retrying the same version perfor · 14 unmodified lines | ||
| 77 | 77 | |
| 78 | 78 | ## Host Service Lifecycle |
| 79 | 79 | |
| 80 | −The systemd user service is a host lifecycle concern, not a T3 Connect resource. The standalone | |
| 81 | −`t3 service install`, `uninstall`, `update`, and `status` commands own it. Install and update both | |
| 82 | −reconcile the unit through `BootService`; running `npx t3@latest service update` therefore pins and | |
| 83 | −activates the latest CLI release without requiring a connected client. | |
| 80 | +The systemd user service or macOS LaunchAgent is a host lifecycle concern, not a T3 Connect | |
| 81 | +resource. The standalone `t3 service install`, `uninstall`, `update`, and `status` commands own it. | |
| 82 | +Install and update both reconcile the unit through `BootService`; running | |
| 83 | +`npx t3@latest service update` therefore pins and activates the latest CLI release without requiring | |
| 84 | +a connected client. | |
| 84 | 85 | |
| 85 | 86 | The `t3 connect` onboarding flow may offer service installation, but it calls the same reconciliation |
| 86 | 87 | operation as `t3 service install`. Connect logout only disables cloud access and clears its |
| @@ -88,9 +89,13 @@ authorization; it does not uninstall the host service. · 1 unmodified line | ||
| 88 | 89 | |
| 89 | 90 | ## Process Handoff |
| 90 | 91 | |
| 91 | −For `boot-service`, the server atomically rewrites the T3-managed user unit to point at the verified | |
| 92 | −runtime, reloads systemd, and restarts the unit. Reload and restart failures restore the previous | |
| 93 | −unit before returning an error. | |
| 92 | +For a systemd `boot-service`, the server atomically rewrites the T3-managed user unit to point at | |
| 93 | +the verified runtime, reloads systemd, and restarts the unit. Reload and restart failures restore | |
| 94 | +the previous unit before returning an error. | |
| 95 | + | |
| 96 | +For a macOS `boot-service`, the LaunchAgent always starts a stable entry path. The server atomically | |
| 97 | +switches that path to the verified runtime and asks launchd to restart the job. A rejected restart | |
| 98 | +restores the previous runtime link before returning an error. | |
| 94 | 99 | |
| 95 | 100 | For `respawn`, the server starts a detached, delayed replacement that replays the original CLI |
| 96 | 101 | arguments. It then acknowledges the request and schedules the current process to exit. The delays |
| @@ -1,7 +1,14 @@ | ||
| 1 | 1 | # Running T3 Code in the Background |
| 2 | 2 | |
| 3 | −On a Linux host, T3 Code can run as a background service for your user. It starts when the machine | |
| 4 | −boots and keeps running after you log out. | |
| 3 | +On macOS or Linux, T3 Code can run as a background service for your user. The simplest setup is: | |
| 4 | + | |
| 5 | +```sh | |
| 6 | +npx t3 connect | |
| 7 | +``` | |
| 8 | + | |
| 9 | +After T3 Connect links the machine, accept the default background setup. T3 Code starts immediately | |
| 10 | +and returns automatically after a reboot. On macOS, the per-user LaunchAgent starts after you sign | |
| 11 | +in. On Linux, the systemd user service starts at boot and keeps running after you log out. | |
| 5 | 12 | |
| 6 | 13 | ## Manage the Service |
| 7 | 14 | |
| @@ -33,10 +40,10 @@ Updating restarts T3 Code briefly. Let active agent work and terminal commands f · 25 unmodified lines | ||
| 33 | 40 | |
| 34 | 41 | ## Using It with T3 Connect |
| 35 | 42 | |
| 36 | −T3 Connect may offer to install the service during setup so the host stays reachable after you log | |
| 37 | −out. This is only an onboarding shortcut: the service and T3 Connect are managed separately. | |
| 43 | +T3 Connect offers to install the service during setup so the host starts automatically and stays | |
| 44 | +reachable in the background. The service and T3 Connect are still managed separately. | |
| 38 | 45 | |
| 39 | 46 | Signing out of T3 Connect does not remove the service. Use `t3 service uninstall` when you no longer |
| 40 | 47 | want T3 Code to start in the background. |
| 41 | 48 | |
| 42 | −The background service currently requires Linux with systemd. | |
| 49 | +The background service requires macOS with launchd or Linux with systemd. | |