Skip to content

docs: make the standalone installer the primary way to get the CLI #11696

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
juliusmarminge merged 6 commits into from
Sep 16, 2026
Merged

docs: make the standalone installer the primary way to get the CLI #11696

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
bcce948
docs: make the standalone installer the primary way to get the CLI
juliusmarminge Sep 14, 2026
d68ad05
docs: cut the explanatory prose from the install guides
juliusmarminge Sep 14, 2026
b69cdf7
docs(user): describe t3 update plus t3 service restart as the service…
juliusmarminge Sep 14, 2026
56e7026
docs(user): name the SSH host requirements and the npx update path
juliusmarminge Sep 16, 2026
8f73bba
docs(user): say what to do when t3 is not on PATH after install
juliusmarminge Sep 16, 2026
7473cc1
docs(user): note that the npx path needs Node
juliusmarminge Sep 16, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 10 additions & 6 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
```

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

Expand Down
21 changes: 13 additions & 8 deletions apps/marketing/src/pages/download.astro
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>
<p class="cli-note">No Node.js? The preview build installs as a single download:</p>
<code class="cli-line">curl -fsSL https://t3.codes/install.sh | sh</code>
<code class="cli-line">irm https://t3.codes/install.ps1 | iex</code>
<code class="cli-line cli-line--stable">curl -fsSL https://t3.codes/install.sh | sh</code>
<code class="cli-line cli-line--stable">irm https://t3.codes/install.ps1 | iex</code>
<code class="cli-line cli-line--nightly">curl -fsSL https://t3.codes/install.sh | T3CODE_CHANNEL=nightly sh</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>

Expand Down Expand Up @@ -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 {
display: flex;
.download-page[data-channel="nightly"] .cli-line--nightly {
display: block;
}

.platform-header {
Expand Down
83 changes: 29 additions & 54 deletions docs/user/background-service.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

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
Running `t3 service install` again repairs a service that `t3 service status`
reports as broken.

`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
```
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.

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.
`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

Expand Down Expand Up @@ -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`.

Expand Down
59 changes: 37 additions & 22 deletions docs/user/install.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,38 +5,53 @@ 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
```

On Windows, in PowerShell:

```powershell
irm https://t3.codes/install.ps1 | iex
```

This starts the server and opens the local web app. Run
`npx t3@latest --help` for command-line options.
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

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)):
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
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

Expand All @@ -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.

Expand Down
31 changes: 15 additions & 16 deletions docs/user/remote-access.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -42,13 +42,13 @@ For a command-line host, replace `<private-ip>` with the host's LAN or tailnet
address:

```bash
npx t3 serve --host <private-ip>
t3 serve --host <private-ip>
```

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**
Expand Down Expand Up @@ -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/`.
Expand All @@ -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

Expand All @@ -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.
Expand All @@ -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.
Expand Down
20 changes: 10 additions & 10 deletions docs/user/updating.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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@<client-version> service update
t3 update <client-version>
Comment thread
coderabbitai[bot] marked this conversation as resolved.
```

Replace `<client-version>` 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 `<client-version>` 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@<client-version>`. 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@<client-version>` with the same subcommand and options.

## If an update fails

Expand Down
Loading
Loading