> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/pingdotgg/t3code/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Complete installation guide for T3 Code - NPM, desktop app, and prerequisites

## Prerequisites

Before installing T3 Code, ensure you have the required dependencies.

### Codex CLI (Required)

<Warning>
  T3 Code requires Codex CLI to be installed and authenticated. This is not optional.
</Warning>

T3 Code is currently Codex-first and wraps the Codex app server:

<Steps>
  <Step title="Install Codex CLI">
    Install the Codex CLI so that `codex` is available on your PATH:

    ```bash theme={null}
    # Follow installation instructions at:
    # https://github.com/openai/codex
    ```

    Verify installation:

    ```bash theme={null}
    codex --version
    ```
  </Step>

  <Step title="Authenticate Codex">
    Authenticate Codex before running T3 Code:

    ```bash theme={null}
    # Use API key or ChatGPT auth supported by Codex
    codex auth
    ```

    <Note>
      T3 Code starts the server via `codex app-server` per session, so authentication must be completed beforehand.
    </Note>
  </Step>
</Steps>

### Runtime Requirements

<Tabs>
  <Tab title="NPX Method">
    **Node.js**: Version 22.13+, 23.4+, or 24.10+

    ```bash theme={null}
    node --version
    # Should be v22.13+, v23.4+, or v24.10+
    ```

    The NPX method will use your system Node.js to run the server.
  </Tab>

  <Tab title="Desktop App">
    **No additional runtime required**

    The desktop app bundles everything needed, including:

    * Electron runtime
    * Node.js environment
    * All dependencies

    You only need Codex CLI installed separately.
  </Tab>
</Tabs>

## Installation Methods

### NPX (Recommended for quick start)

The fastest way to run T3 Code without installation:

```bash theme={null}
npx t3
```

**What this does:**

* Downloads the latest published version from npm
* Starts the Node.js WebSocket server
* Serves the React web interface
* Opens `http://localhost:3773` in your browser
* Connects via `ws://localhost:3773`

<Tip>
  Use NPX when you want to:

  * Try T3 Code without committing to an installation
  * Always run the latest version
  * Use T3 Code occasionally from any directory
</Tip>

**Package details:**

```json theme={null}
{
  "name": "t3",
  "version": "0.0.3",
  "bin": {
    "t3": "./dist/index.mjs"
  }
}
```

### Desktop Application

For a native experience with better system integration:

<Steps>
  <Step title="Download the installer">
    Visit the [GitHub Releases page](https://github.com/pingdotgg/t3code/releases) and download for your platform:

    <Tabs>
      <Tab title="macOS">
        **Download**: `.dmg` file

        Available architectures:

        * **arm64** (Apple Silicon: M1, M2, M3)
        * **x64** (Intel Macs)

        ```bash Build from source theme={null}
        # Build arm64 DMG
        bun run dist:desktop:dmg:arm64

        # Build x64 DMG
        bun run dist:desktop:dmg:x64
        ```
      </Tab>

      <Tab title="Windows">
        **Download**: `.exe` installer (NSIS)

        Architecture:

        * **x64** (64-bit Windows)

        ```bash Build from source theme={null}
        bun run dist:desktop:win
        ```
      </Tab>

      <Tab title="Linux">
        **Download**: `.AppImage`

        Architecture:

        * **x64** (64-bit Linux)

        ```bash Build from source theme={null}
        bun run dist:desktop:linux
        ```

        Make the AppImage executable:

        ```bash theme={null}
        chmod +x T3Code-*.AppImage
        ./T3Code-*.AppImage
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Install the application">
    <Tabs>
      <Tab title="macOS">
        1. Open the downloaded `.dmg` file
        2. Drag **T3 Code** to your **Applications** folder
        3. Launch from Applications or Spotlight

        <Note>
          On first launch, you may need to allow the app in **System Settings → Privacy & Security**
        </Note>
      </Tab>

      <Tab title="Windows">
        1. Run the downloaded `.exe` installer
        2. Follow the installation wizard
        3. Launch from the Start Menu or desktop shortcut
      </Tab>

      <Tab title="Linux">
        No installation required for AppImage:

        ```bash theme={null}
        chmod +x T3Code-*.AppImage
        ./T3Code-*.AppImage
        ```

        Optional: Integrate with system menu using AppImageLauncher
      </Tab>
    </Tabs>
  </Step>

  <Step title="Launch and verify">
    Open the T3 Code desktop app. It should:

    * Start the embedded server
    * Load the web interface in the Electron window
    * Connect to the WebSocket server
    * Be ready to create your first session

    <Check>
      If the interface loads and you can access the chat, installation is complete!
    </Check>
  </Step>
</Steps>

### Development Installation

For contributors and developers working on T3 Code itself:

<Warning>
  This method is for T3 Code development only, not for end users.
</Warning>

<Steps>
  <Step title="Clone the repository">
    ```bash theme={null}
    git clone https://github.com/pingdotgg/t3code.git
    cd t3code
    ```
  </Step>

  <Step title="Install dependencies">
    T3 Code uses Bun as the package manager:

    ```bash theme={null}
    # Install Bun if needed
    curl -fsSL https://bun.sh/install | bash

    # Install dependencies
    bun install
    ```

    **Required versions:**

    * **Bun**: 1.3.9+
    * **Node**: 24.13.1+ (for runtime)
  </Step>

  <Step title="Run development server">
    <Tabs>
      <Tab title="Web Development">
        Run with hot reload:

        ```bash theme={null}
        bun run dev
        ```

        This starts:

        * Server at `localhost:3773`
        * Web client with Vite HMR
      </Tab>

      <Tab title="Desktop Development">
        Run the Electron app in development mode:

        ```bash theme={null}
        bun run dev:desktop
        ```

        For isolated testing (different port set):

        ```bash theme={null}
        T3CODE_DEV_INSTANCE=feature-xyz bun run dev:desktop
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Build for production">
    <CodeGroup>
      ```bash Server & Web theme={null}
      bun run build
      bun run start
      ```

      ```bash Desktop App theme={null}
      # Build all desktop artifacts
      bun run dist:desktop:artifact

      # Or specific platform:
      bun run dist:desktop:dmg      # macOS DMG
      bun run dist:desktop:win      # Windows installer
      bun run dist:desktop:linux    # Linux AppImage
      ```
    </CodeGroup>
  </Step>
</Steps>

## Architecture Overview

Understanding the installation helps clarify T3 Code's architecture:

```
┌─────────────────────────────────────────┐
│  Installation Method                     │
├─────────────────────────────────────────┤
│  NPX          │  Desktop App             │
│  - CLI entry  │  - Electron wrapper      │
│  - NPM pkg    │  - Bundled server        │
└───────┬───────┴──────────┬───────────────┘
        │                  │
        v                  v
┌─────────────────────────────────────────┐
│  apps/server (Node.js)                  │
│  - WebSocket server (port 3773)         │
│  - HTTP server (serves React app)       │
│  - ProviderManager                      │
│  - CodexAppServerManager                │
└──────────────┬──────────────────────────┘
               │ JSON-RPC over stdio
┌──────────────▼──────────────────────────┐
│  codex app-server                       │
│  - Requires Codex CLI installed         │
│  - Started per session                  │
└─────────────────────────────────────────┘
```

## Verification

Verify your installation is working correctly:

<Steps>
  <Step title="Check Codex CLI">
    ```bash theme={null}
    codex --version
    # Should output version information

    which codex
    # Should output path to codex binary
    ```
  </Step>

  <Step title="Check T3 Code">
    <Tabs>
      <Tab title="NPX">
        ```bash theme={null}
        npx t3 --version
        # Should output: 0.0.3 (or current version)
        ```
      </Tab>

      <Tab title="Desktop">
        Open the app and check **Help → About** (macOS) or **Help → About** (Windows/Linux)
      </Tab>
    </Tabs>
  </Step>

  <Step title="Test connection">
    1. Start T3 Code
    2. Open browser to `http://localhost:3773` (NPX) or use the desktop window
    3. Check that WebSocket connects successfully
    4. Create a test session

    <Check>
      If you can start a session and interact with Codex, installation is complete!
    </Check>
  </Step>
</Steps>

## Uninstallation

<Tabs>
  <Tab title="NPX">
    NPX runs T3 Code without permanent installation. To clear cache:

    ```bash theme={null}
    npm cache clean --force
    ```
  </Tab>

  <Tab title="Desktop App">
    <Tabs>
      <Tab title="macOS">
        1. Move **T3 Code.app** from Applications to Trash
        2. Remove application support files (optional):
           ```bash theme={null}
           rm -rf ~/Library/Application\ Support/T3Code
           rm -rf ~/Library/Caches/T3Code
           ```
      </Tab>

      <Tab title="Windows">
        1. Uninstall via **Settings → Apps → T3 Code → Uninstall**
        2. Or run the uninstaller from the installation directory
      </Tab>

      <Tab title="Linux">
        Simply delete the AppImage file:

        ```bash theme={null}
        rm T3Code-*.AppImage
        ```
      </Tab>
    </Tabs>
  </Tab>
</Tabs>

## Troubleshooting Installation

<AccordionGroup>
  <Accordion title="Codex CLI not found during installation">
    T3 Code requires Codex CLI to be installed first:

    ```bash theme={null}
    # Verify Codex is on PATH
    which codex

    # If not found, install from:
    # https://github.com/openai/codex
    ```
  </Accordion>

  <Accordion title="Node version mismatch (NPX)">
    T3 Code requires Node.js 22.13+, 23.4+, or 24.10+:

    ```bash theme={null}
    node --version

    # Use nvm to install the correct version:
    nvm install 24
    nvm use 24
    ```
  </Accordion>

  <Accordion title="Desktop app won't launch (macOS)">
    macOS may block unsigned applications:

    1. Go to **System Settings → Privacy & Security**
    2. Click **Open Anyway** next to the T3 Code warning
    3. Or right-click the app and select **Open**
  </Accordion>

  <Accordion title="Port 3773 already in use">
    Another instance of T3 Code is running:

    ```bash theme={null}
    # Find the process
    lsof -i:3773

    # Kill it
    lsof -ti:3773 | xargs kill -9
    ```
  </Accordion>

  <Accordion title="Build failed (development)">
    Ensure you're using the correct Bun version:

    ```bash theme={null}
    bun --version
    # Should be 1.3.9+

    # Reinstall dependencies
    rm -rf node_modules
    bun install

    # Try building again
    bun run build
    ```
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Quickstart Guide" icon="rocket" href="/quickstart">
    Get T3 Code running and start your first session
  </Card>

  <Card title="Configuration" icon="gear" href="/configuration/server-options">
    Customize server options and environment variables
  </Card>

  <Card title="Runtime Modes" icon="shield-halved" href="/concepts/runtime-modes">
    Understand Full Access vs Supervised modes
  </Card>

  <Card title="Development Setup" icon="code" href="/development/setup">
    Set up a development environment for contributing
  </Card>
</CardGroup>

<Note>
  **Need help?** Join our [Discord community](https://discord.gg/jn4EGJjrvv) or open an issue on [GitHub](https://github.com/pingdotgg/t3code/issues).
</Note>