# How to Run the T3 Code Project: Local Development and Production Deployment

> Learn how to run the T3 code project locally or deploy it. Start development with bun run dev or use npx t3 to run the CLI from any directory. Get the T3 code project running easily.

- Repository: [Ping.gg/t3code](https://github.com/pingdotgg/t3code)
- Tags: how-to-guide
- Published: 2026-04-18

---

**Run `bun run dev` to start the development server with hot-reload, or execute `npx t3` to run the pre-built CLI from any directory without cloning the repository.**

T3 Code is a minimal web-based GUI that wraps a Codex or Claude provider inside a Node.js WebSocket server, serving a React and Vite client. If you want to run the T3 Code project locally or deploy it to production, this guide covers the complete setup process from installation to runtime configuration.

## Understanding the T3 Code Architecture

Before running the project, it helps to understand the three-layer runtime stack defined in [`.docs/architecture.md`](https://github.com/pingdotgg/t3code/blob/main/.docs/architecture.md).

### The Three-Layer Runtime Stack

1. **Provider runtime**: A `codex app-server` process that executes coding agents via JSON-RPC over stdio.
2. **Server layer**: The Node.js process in `apps/server` that starts the provider, persists state, and exposes a typed WebSocket API. The entry point is [`apps/server/src/server.ts`](https://github.com/pingdotgg/t3code/blob/main/apps/server/src/server.ts).
3. **Browser client**: A Vite-powered React app in `apps/web` that connects via typed WebSocket transport (`WsTransport`). The client router is defined in [`apps/web/src/router.ts`](https://github.com/pingdotgg/t3code/blob/main/apps/web/src/router.ts).

### Data Flow and Component Interaction

The data flow follows this path: Browser (React) → WebSocket (typed pushes) → Server (`OrchestrationEngine`) → Provider (`codex app-server`). When the server boots, it composes Effect-Layer modules for persistence, Git integration, authentication, and analytics, then launches the HTTP and WebSocket stack via `makeServerLayer`.

## Prerequisites and Installation

### Installing Bun and Optional Tooling

T3 Code uses **Bun** as the runtime manager. You can install Bun via the official installer. If you use `mise` for tool versioning, run `mise install` first to ensure consistent environment setup.

### Project Dependencies Setup

Clone the repository and install dependencies:

```bash
bun install .

```

This command fetches all dependencies for the server, web client, and shared packages.

## Running T3 Code in Development Mode

### Starting the Dev Server

To run T3 Code in development with hot-reload, execute:

```bash
bun run dev

```

This starts the Node server and Vite dev server concurrently. By default, the web interface is available at `http://localhost:3000` and the WebSocket server listens on port `3773`.

### Desktop Development Mode

For desktop development (Electron-style), run:

```bash
bun run dev:desktop

```

This launches the bundled desktop runtime alongside the development servers. To isolate instances for feature branches, set the `T3CODE_DEV_INSTANCE` environment variable:

```bash
T3CODE_DEV_INSTANCE=feature-xyz bun run dev:desktop

```

## Building and Running for Production

### Production Build Process

To build the T3 Code project for production:

```bash
bun run build

```

This compiles the client using `vite build` and prepares the server assets. Then start the production server:

```bash
bun run start

```

The server runs in production mode, serving the built client and handling WebSocket connections.

### Desktop Distribution

To package the desktop application as a macOS DMG:

```bash
bun run dist:desktop:dmg

```

This uses `electron-builder` under the hood to create a signed `.dmg` file for arm64 architecture, outputting to `./dist/t3-code-*.dmg`.

## Running the Pre-built CLI

After publishing, you can run T3 Code from any directory without cloning the repository:

```bash
npx t3

```

This downloads the latest binary, starts the server, and opens the web UI in your default browser.

## Key Configuration and Runtime Components

When running the project, several key components initialize:

- **`ServerConfig`** – Located in [`apps/server/src/config.ts`](https://github.com/pingdotgg/t3code/blob/main/apps/server/src/config.ts), reads environment variables and CLI flags.
- **`websocketRpcRouteLayer`** – Defined in [`apps/server/src/ws.ts`](https://github.com/pingdotgg/t3code/blob/main/apps/server/src/ws.ts), registers the typed RPC endpoint.
- **`ProviderAdapterRegistryLive`** – In [`apps/server/src/provider/Layers/ProviderAdapterRegistry.ts`](https://github.com/pingdotgg/t3code/blob/main/apps/server/src/provider/Layers/ProviderAdapterRegistry.ts), wires adapters for Codex, Claude, OpenCode, and Cursor.
- **`OrchestrationEngine`** – Found in [`apps/server/src/orchestration/Layers/OrchestrationEngine.ts`](https://github.com/pingdotgg/t3code/blob/main/apps/server/src/orchestration/Layers/OrchestrationEngine.ts), handles event persistence and emits domain events for the UI.

All communication follows the typed WebSocket contracts defined in [`packages/contracts/src/ws.ts`](https://github.com/pingdotgg/t3code/blob/main/packages/contracts/src/ws.ts).

## Summary

- **T3 Code** combines a Codex/Claude provider, Node.js WebSocket server, and React/Vite client into a minimal coding GUI.
- **Run locally** with `bun run dev` for hot-reload development or `bun run dev:desktop` for the desktop version.
- **Deploy to production** using `bun run build` followed by `bun run start`, or distribute desktop builds via `bun run dist:desktop:dmg`.
- **Use the CLI** anywhere with `npx t3` without installing the repository.
- **Key files** to understand: [`apps/server/src/server.ts`](https://github.com/pingdotgg/t3code/blob/main/apps/server/src/server.ts), [`apps/web/src/router.ts`](https://github.com/pingdotgg/t3code/blob/main/apps/web/src/router.ts), and [`packages/contracts/src/ws.ts`](https://github.com/pingdotgg/t3code/blob/main/packages/contracts/src/ws.ts).

## Frequently Asked Questions

### How do I install dependencies for the T3 Code project?

Run `bun install .` in the repository root to fetch all dependencies for the server, web client, and shared packages. If you use `mise` for tool versioning, run `mise install` first to ensure Bun and other tools are available.

### What ports does T3 Code use in development?

By default, the Vite dev server runs on port `3000` for the web interface, while the WebSocket server listens on port `3773` for client-server communication. You can configure these via environment variables in [`apps/server/src/config.ts`](https://github.com/pingdotgg/t3code/blob/main/apps/server/src/config.ts).

### Can I run T3 Code without cloning the repository?

Yes. After the package is published, you can execute `npx t3` from any directory. This command downloads the latest binary, starts the server, and automatically opens the web UI in your default browser without requiring local source code.

### How do I build the desktop version for macOS?

Run `bun run dist:desktop:dmg` to package the application as a signed `.dmg` file for arm64 architecture. This uses `electron-builder` under the hood and outputs the installer to `./dist/t3-code-*.dmg`. For development testing, use `bun run dev:desktop` instead.