diff --git a/README.md b/README.md index 27b5dc491693608b79b6e39f37a72b1007d467fd..28cc78162085cdf197e06197de982d09adab202c 100644 --- a/README.md +++ b/README.md @@ -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) - -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+): +### Command line ```bash -npx t3@latest +curl -fsSL https://t3.codes/install.sh | sh ``` -This will launch T3 Code's backend on your machine as well as the local web app to control your agents. +On Windows, in PowerShell: -Tip: Use `npx t3@latest --help` for the full CLI reference. +```powershell +irm https://t3.codes/install.ps1 | iex +``` + +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. + +To try it once without installing, run `npx t3@latest` instead. ### Desktop app diff --git a/apps/marketing/src/pages/download.astro b/apps/marketing/src/pages/download.astro index 95c6f513f665bd40e531e8d63fcc45079c341db1..f3212d1e38ae40d35acc3e9aa8372d95ba938ee0 100644 --- a/apps/marketing/src/pages/download.astro +++ b/apps/marketing/src/pages/download.astro @@ -131,10 +131,13 @@ const imageProps = {

Terminal

- npx t3@nightly -

No Node.js? The preview build installs as a single download:

- curl -fsSL https://t3.codes/install.sh | sh - irm https://t3.codes/install.ps1 | iex + curl -fsSL https://t3.codes/install.sh | sh + irm https://t3.codes/install.ps1 | iex + curl -fsSL https://t3.codes/install.sh | T3CODE_CHANNEL=nightly sh + $env:T3CODE_CHANNEL="nightly"; irm https://t3.codes/install.ps1 | iex +

Or try it once without installing:

+ npx t3@latest + npx t3@nightly @@ -402,16 +405,18 @@ const imageProps = { gap: 0.75rem; } - .platform-section--cli { - display: none; - } - .download-page[data-channel="nightly"] .platform-section--mobile { display: none; } - .download-page[data-channel="nightly"] .platform-section--cli { - display: flex; + /* 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"] .cli-line--nightly { + display: block; } .platform-header { diff --git a/docs/user/background-service.md b/docs/user/background-service.md index e82d97b8c3f4fb09fc18244656e36d51c7c779bd..9964fba54f74c83f8ba4b15f493ff76392ad5481 100644 --- a/docs/user/background-service.md +++ b/docs/user/background-service.md @@ -5,65 +5,40 @@ to keep a terminal open. ## Manage the service -Run these commands on the machine that will host T3 Code: +Install the `t3` CLI first ([Install T3 Code](./install.md#command-line)), then +run these commands on the machine that will host T3 Code: -| Task | Command | -| ------------------------------- | --------------------------------- | -| Install and start | `npx t3@latest service install` | -| Inspect status and log location | `npx t3@latest service status` | -| Update or repair | `npx t3@latest service update` | -| Stop and remove from startup | `npx t3@latest service uninstall` | +| Task | Command | +| ------------------------------- | ---------------------- | +| Install and start | `t3 service install` | +| Inspect status and log location | `t3 service status` | +| Move to a newer release | `t3 update` | +| Restart | `t3 service restart` | +| Stop and remove from startup | `t3 service uninstall` | Uninstalling the service leaves your projects, threads, and settings intact. +Running `t3 service install` again repairs a service that `t3 service status` +reports as broken. -Install and update use the version of the CLI you invoke. For nightly, use -`npx t3@nightly service update`; replace `nightly` with an exact version to pin -one. An older CLI refuses to replace a newer service unless you explicitly add -`--allow-downgrade`. - -Updating restarts the server. Finish active work first, and wait for any remote -update already in progress. To match a remote client's version, follow +`t3 update` downloads the newest release on your channel and switches `t3` +and the service to it. Restarting interrupts running agent turns, terminals, +and remote clients, so it asks first; answer no and the service keeps running +the old version until you run `t3 service restart`. Pass `--yes` from a +script. A server you started by hand is left running; stop and start it again +to pick up the new version. Wait for any remote update already in progress +before updating; to match a remote client's version, follow [Updating T3 Code](./updating.md). -Self-contained builds install as a download from the T3 Code GitHub release -instead of through npm, so the machine running the service does not need -Node.js or npm once the CLI is on it. To get the CLI onto a machine without -Node, run the install script: - -```sh -curl -fsSL https://t3.codes/install.sh | sh -``` - -On Windows, run `irm https://t3.codes/install.ps1 | iex` in PowerShell instead. - -It places `t3` in `~/.local/bin` and reuses the same download when you later -run `t3 service install`. It follows the stable train by default; set -`T3CODE_CHANNEL=nightly` for nightlies, `T3CODE_VERSION` to pin an exact -version, or `T3CODE_RELEASE_BASE_URL` to download from a mirror. - -`preview` is a third train that maintainers cut from unreleased branches to -exercise the release pipeline. Those builds can be broken, receive no fixes, -and are never offered as updates; the installer and `t3 update` only take you -there when you ask for the channel explicitly, and warn you when they do. - -Once a self-contained `t3` is installed, `t3 update` moves the machine to a -newer one without npm: it downloads the newest release on the channel the -running `t3` came from, verifies it, and points the `t3` launcher at it. When -a background service is installed for the same T3 home it asks before -restarting it, since a restart interrupts running agent turns, terminals, and -remote clients; answer no and the service keeps the old version until you run -`t3 service update`. From a script there is no prompt, so pass `--yes` to -restart the service. A server you started by hand is never touched; the -command tells you it is still on the old version so you can restart it -yourself. Pass an exact version (`t3 update 0.0.41-preview.20260912.1595`) to -pin one, `--channel` to follow a different release train (moving onto preview from stable or nightly asks for confirmation), or -`--allow-downgrade` to move backwards. - -`t3 uninstall` reverses the install script: it shows what it found (the -background service, the `t3` launcher, every downloaded version under -`~/.t3/runtime`), asks once, and removes them. Your projects, threads, and -settings under `~/.t3/userdata` are kept; delete that directory yourself if -you want them gone too. Pass `--yes` from a script. +Pass an exact version (`t3 update 0.0.42`) to pin one, `--channel nightly` to +switch trains, or `--allow-downgrade` to move backwards. `preview` is a +maintainers' test train: its builds can be broken and are never offered as +updates, so the installer and `t3 update` ask for confirmation before +installing one. + +`t3 uninstall` removes the background service, the `t3` launcher, and the +downloaded versions after showing you the list and asking once. Your projects, +threads, and settings under `~/.t3/userdata` are kept. Pass `--yes` from a +script. ## Platform support @@ -114,7 +89,7 @@ that session open. On macOS, check **System Settings → General → Login Items** if the service no longer starts at login. If agent work cannot access Desktop, Documents, or -Downloads, it may need Full Disk Access for the Node executable listed in +Downloads, it may need Full Disk Access for the `t3` executable listed in `ProgramArguments` in `~/Library/LaunchAgents/com.t3tools.t3code.service.plist`. diff --git a/docs/user/install.md b/docs/user/install.md index a4ed171bd986a862233f5413676eefdf3dad0ec8..2a7e7dc7e749c6769bca2097cccc992fd02c4820 100644 --- a/docs/user/install.md +++ b/docs/user/install.md @@ -5,28 +5,44 @@ desktop, web, or mobile app. Set up the machine where the agents will work first ## Requirements -`npx t3` needs Node.js only to run npm itself; the CLI it installs is a -self-contained executable. SSH hosts and WSL backends need Node.js 22.16+ -(22.x), 23.11+ (23.x), or 24.10 and later. The native desktop app includes its -server runtime. - You need an installed, authenticated provider before starting a thread. You can launch T3 Code and configure providers afterwards. -## Run without installing +## Command line ```bash -npx t3@latest +curl -fsSL https://t3.codes/install.sh | sh ``` -This starts the server and opens the local web app. Run -`npx t3@latest --help` for command-line options. +On Windows, in PowerShell: -The executable is built for Apple Silicon Macs, Linux, and Windows. There is -no Intel Mac build of it, because Node cannot produce a single executable for -that platform; the Intel desktop app is unaffected. To run a standalone server -on an Intel Mac, build it from source. You need Node.js 24 and `vp` (see -[Install vp](https://github.com/pingdotgg/t3code#install-vp)): +```powershell +irm https://t3.codes/install.ps1 | iex +``` + +This puts `t3` in `~/.local/bin`. If your shell reports `command not found` +afterwards, that directory is not on your `PATH` yet; the installer prints the +line to add. Set `T3CODE_CHANNEL=nightly` to install the nightly train, or +`T3CODE_VERSION` to pin an exact version. + +| Task | Command | +| ------------------------------------------------ | --------------------------------------------------------- | +| Start the server and open the web app | `t3` | +| Start the server without a browser | `t3 serve` | +| Keep it running in the background (macOS, Linux) | `t3 service install` ([details](./background-service.md)) | +| Move to the newest release | `t3 update` | +| Remove it again | `t3 uninstall` | + +Run `t3 --help` for the full reference. + +To try T3 Code once without installing it, run `npx t3@latest` instead (needs +Node.js for `npx`). + +### Intel Macs + +There is no `t3` executable for Intel Macs (the desktop app is available). To +run a server there, build it from source with Node.js 24 and `vp` +([Install vp](https://github.com/pingdotgg/t3code#install-vp)): ```bash git clone https://github.com/pingdotgg/t3code @@ -34,9 +50,8 @@ cd t3code && vp i && vp run build:desktop node apps/server/dist/bin.mjs ``` -A server run this way is a plain Node program: `t3 update` and the background -service do not apply, so update it with `git pull` and a rebuild, and start it -however you run other Node processes. +`t3 update` and the background service do not apply to a server run this way; +update it with `git pull` and a rebuild. ## Desktop app @@ -53,20 +68,20 @@ or use a package manager: ### Windows Subsystem for Linux Choose a WSL distro in **Settings → Connections** to run agents and projects -there. Install Node.js and provider CLIs inside that distro. T3 Code installs its -matching server runtime there automatically; the first launch after an app -update can take longer. +there. Install the provider CLIs inside that distro. T3 Code installs its own +server runtime there automatically; the first launch after an app update can +take longer. ### Open a project from a terminal With the desktop app already running on the same machine: ```bash -npx t3 app +t3 app ``` This opens a new thread for the current directory, adding the project if needed. -Pass a path, such as `npx t3 app ../my-project`, to open another directory. It requires +Pass a path, such as `t3 app ../my-project`, to open another directory. It requires the desktop app, so a standalone server or an SSH session is not enough. If the command cannot reach the app, start or update the desktop app and try again. diff --git a/docs/user/remote-access.md b/docs/user/remote-access.md index ade332337187497b4a782a9e3b4a0eb58a273812..12658d3e07202ae46c437492be9c0187d93b92bf 100644 --- a/docs/user/remote-access.md +++ b/docs/user/remote-access.md @@ -12,12 +12,12 @@ Connections**, sign in, and enable **T3 Connect** for that environment. For a command-line host, run: ```bash -npx t3@latest connect +t3 connect ``` Follow the sign-in instructions. Setup offers a [background service](./background-service.md); if you decline it, start the -server with `npx t3 serve`. Saving your sign-in alone does not make the machine +server with `t3 serve`. Saving your sign-in alone does not make the machine reachable. 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 `` with the host's LAN or tailnet address: ```bash -npx t3 serve --host +t3 serve --host ``` If a server is already running, generate a fresh link without restarting it: ```bash -npx t3 pair +t3 pair ``` 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. To start a command-line server with Tailscale HTTPS: ```bash -npx t3 serve --tailscale-serve +t3 serve --tailscale-serve ``` For an already-running server: ```bash -npx t3 pair --tailscale +t3 pair --tailscale ``` The pairing link uses an address such as `https://machine.tailnet.ts.net/`. @@ -106,7 +106,7 @@ tailscale serve --https=443 off ``` If that port is already in use, choose another with -`--tailscale-serve-port`. See `npx t3 pair --help` for other pairing options. +`--tailscale-serve-port`. See `t3 pair --help` for other pairing options. ### Hosted web app @@ -125,18 +125,17 @@ In the desktop app, open **Settings → Connections → Add environment**, choos or reuses a server there and opens the port forward for you. Projects, provider credentials, and agent work stay on the remote machine. -The remote host needs a compatible [Node.js installation](./install.md#requirements) -and [provider setup](./install.md#providers). If launch cannot find Node or reports -an incompatible version, check it through a non-interactive SSH session: +The remote host must be Linux or an Apple Silicon Mac with `curl` or `wget`, +`tar`, `sha256sum` or `shasum`, and [provider setup](./install.md#providers). +The first launch downloads T3 Code's server to `~/.t3/runtime` on the host, so +it takes longer than later ones. +Provider CLIs must be on the `PATH` of a non-interactive login shell there; +check with: ```bash -ssh user@example.com 'sh -lc "command -v node && node --version"' +ssh user@example.com 'sh -lc "command -v claude codex"' ``` -Configure your version manager for non-interactive shells if this differs from -your normal terminal. With nvm, setting a compatible default, such as -`nvm alias default 24`, can resolve the problem. - If SSH reconnecting fails after an app update, retry the launch once. Removing the connection stops a server that T3 Code launched; a server that was already running is left alone. @@ -149,7 +148,7 @@ For Antigravity's Google callback on a remote host, see On the host, **Settings → Connections** lets authorized administrators create pairing links and revoke client sessions. Revoking an unused link prevents new pairings; revoke a device's session to remove its existing access. Command-line -management is available through `npx t3 auth --help`. +management is available through `t3 auth --help`. A session with an open connection stays listed after its access credential expires. diff --git a/docs/user/updating.md b/docs/user/updating.md index d72df7382f56c092787477a42c743a3ec6c38950..25833d3e79ec7938fcfd734662090e23f2490820 100644 --- a/docs/user/updating.md +++ b/docs/user/updating.md @@ -31,21 +31,21 @@ The offered action depends on how the server runs: | **Update the desktop app** | Update the desktop app on the machine running the server, then reopen it if needed. | | **Copy update command** | Stop the command-line server on its host and relaunch with the copied command, keeping your usual startup options. | -For a background service, run the matching version's CLI on the host: +On the host, run: ```sh -npx t3@ service update +t3 update ``` -Replace `` with the version shown in the notice. Using -`@latest` only resolves the mismatch if your client is on that release. An older -service launcher may require this local update before it supports remote updates -and rollback. +Replace `` with the version shown in the notice. The command +asks before restarting the background service; if you decline, run +`t3 service restart` when you are ready. For a server you started by hand, +stop it and start it again afterwards with your usual options such as `--host` +or `--tailscale-serve`. -For a foreground server, the copied command is `npx t3@`. Add -`serve` if you normally run without a browser, and preserve options such as -`--host` or `--tailscale-serve`. See -[background services](./background-service.md) for service management. +If you run the server with `npx` rather than an installed `t3`, there is +nothing to update on the host: stop the server and relaunch it as +`npx t3@` with the same subcommand and options. ## If an update fails diff --git a/docs/user/welcome-wizard.md b/docs/user/welcome-wizard.md index d124ab6efbe2dfbe48cdbf0cc3392c81fc1897bd..816a24e7d8447bed50d5d8ea4fd17305c7c1649e 100644 --- a/docs/user/welcome-wizard.md +++ b/docs/user/welcome-wizard.md @@ -12,13 +12,14 @@ browser. You can add more computers before continuing: -- **T3 Connect** connects computers that are signed in to your account. Run - `npx t3 connect` on each computer you want to add, then start T3 Code or run - `npx t3 serve` so the computer stays available. +- **T3 Connect** connects computers that are signed in to your account. + [Install the CLI](./install.md#command-line) and run `t3 connect` on each + computer you want to add, then start T3 Code or run `t3 serve` so the + computer stays available. - **Add a computer** connects directly to a server on your network or tailnet. - Start the server with `npx t3 serve`, then run `npx t3 pair --tailscale` and - paste the pairing link. You can also run `npx t3 serve --host
` and - use `npx t3 pair` when the server is already reachable on your network. + Start the server with `t3 serve`, then run `t3 pair --tailscale` and paste + the pairing link. You can also run `t3 serve --host
` and use + `t3 pair` when the server is already reachable on your network. Saved computers and computers discovered through T3 Connect are selected by default. Uncheck any you do not want to set up; this does not disconnect them. @@ -36,9 +37,9 @@ unreadable settings with defaults. T3 Code checks each selected computer for Claude Code and Codex. If an agent is not installed or signed in, select its action to open a terminal with the -correct command ready to run. Install uses the vendor's standalone installer, -which does not need Node or npm and keeps **Update now** working in Settings. -Other providers can be enabled in Settings. +correct command ready to run. Install uses the vendor's own installer, which +keeps **Update now** working in Settings. Other providers can be enabled in +Settings. The setup terminal uses the home directory and environment configured for the selected provider instance. Sensitive values remain redacted in Settings and