Install and reach a useful first thread

Your first decision is where agents will run. Choose the machine that already has the repositories, build tools, and credentials you want the agent to use. That machine becomes the environment host. You may operate it from the same desktop, a browser, or a phone later.

Choose an installation path

flowchart TD
S[Where should agents run?] --> L{This desktop?}
L -->|yes| D[Install desktop app]
L -->|quick trial| N[Run npx t3 at latest]
L -->|no, SSH host| H[Add SSH environment from desktop]
L -->|no, persistent Linux or macOS host| B[Install user background service]
D --> W{Use WSL workspace?}
W -->|yes| WS[Select distro in Connections; install Node and providers inside WSL]
W -->|no| P[Configure provider on host]
N --> P
H --> P
B --> P
WS --> P
P --> O[Run welcome wizard and import projects]
O --> F[Send a small first task]

Command-line and SSH environments require Node.js 22.16+ in the 22 line, 23.11+ in the 23 line, or 24.10+. The desktop app includes its own server runtime.

Install the client or server

For a no-install trial, run:

npx t3@latest

It starts the server and opens its local web client. Use npx t3@latest --help to see launch options.

For desktop, install a release from GitHub or use the supported platform package:

With desktop already running, npx t3 app opens a new thread for the current directory. Pass a path to open another directory. This command talks to the local desktop app; it is not a general command for a standalone or SSH server.

WSL

In Settings → Connections, choose the WSL distribution that should own your projects. Install Node.js and provider CLIs inside that distribution. Desktop installs its matching T3 server there. The first start after an app update can take longer while that runtime catches up.

Background host

On Linux or macOS, install and inspect the user service with:

npx t3@latest service install
npx t3@latest service status

Use service update to repair or update it and service uninstall to stop and remove startup. Uninstalling leaves project, thread, and setting data intact. Linux uses a systemd user service and normally needs lingering; macOS starts at login and requires the machine to remain logged in and awake.

Connect at least one provider

Open Settings → Providers, select the environment, enable a provider, and complete its installation and login on that machine.

If a CLI is not on the server process’s PATH, set Binary path. This is common with language version managers. Provider cards can detect available upgrades; Update now appears only when T3 Code recognizes the installer that owns the binary. Mark API keys and other private instance variables as Sensitive. After you save them, Settings keeps the value available to the provider but no longer shows the original text.

Use the welcome wizard deliberately

The welcome flow has three useful stages:

1. Connect computers. Select the environments you want to set up. Add hosts through T3 Connect or a direct pairing link if needed. Removing a computer from this setup selection does not disconnect it.
2. Check agents. The wizard checks Codex and Claude on each selected computer and can open a terminal with the relevant install or login command. Other providers remain available in Settings.
3. Import projects. Select directories discovered from recent Codex and Claude use. Git repositories appear first and matching remotes are grouped.

The initial project selection favors Git repositories active in the last 30 days with at least three conversations. Linked worktrees, Codex scratch directories under Documents/Codex, and paths under Downloads are excluded. You can change every checkbox or skip import entirely.

Imported history is a practical bridge, not a byte-for-byte archive. T3 Code imports recent visible conversation content, omits tool activity and attachments, and keeps at most 200 messages per conversation. One import attempt reads up to 100 conversation files and 64 MiB per project, with at most 100,000 input records; individual files larger than 16 MiB are skipped. Large histories may require another pass. Completed conversations are not duplicated, and navigation pauses while an import is running.

The setup terminal uses the selected provider instance’s home and environment. Sensitive settings stay redacted in the interface and terminal metadata while the process can use them.

Verify the installation

Create or import one small project, then start a thread with a bounded prompt such as: “Read the repository README and tell me the test command. Do not change files.” Choose Supervised for this check. A healthy setup proves four things:

• the client reaches the intended environment;
• the environment can read the project directory;
• the provider is authenticated and can start a session;
• questions, responses, and permission requests return to the thread.

After that, try a small edit and inspect the diff. Do not diagnose Git, SDK, and provider failures at once; the read-only task separates basic connectivity from toolchain setup.

Keep client and server versions aligned

The app in front of you and the environment server can be on different versions. When a mismatch appears, update the machine named in the notice after active work finishes. The update choices and recovery behavior live in Personalize, measure usage, update, and protect privacy.

Source trail

Sources: install, welcome wizard, background service, and updating.