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

# Configuration

> Server runtime configuration interfaces and environment setup

## Overview

The T3 Code server uses a layered configuration system powered by Effect, with support for CLI flags, environment variables, and runtime defaults.

## ServerConfig

Core runtime configuration service that defines process-level server settings and networking parameters.

**Service Tag:** `t3/config/ServerConfig`

**Source:** `apps/server/src/config.ts:36`

### ServerConfigShape

<ParamField path="mode" type="RuntimeMode" required>
  Runtime mode: `"web"` or `"desktop"`

  * **web**: Production mode with dynamic port allocation
  * **desktop**: Loopback-only mode with fixed defaults
</ParamField>

<ParamField path="port" type="number" required>
  HTTP/WebSocket server port (1-65535)

  Defaults to `3773` in desktop mode, or dynamically allocated in web mode.
</ParamField>

<ParamField path="host" type="string | undefined">
  Host interface to bind

  * `undefined`: Bind to all interfaces (web mode default)
  * `"127.0.0.1"`: Loopback only (desktop mode default)
  * `"0.0.0.0"`: Explicit wildcard binding
  * Any valid IP or hostname
</ParamField>

<ParamField path="cwd" type="string" required>
  Current working directory of the server process
</ParamField>

<ParamField path="stateDir" type="string" required>
  State directory path for database, logs, and runtime state

  Contains:

  * `state.sqlite`: SQLite database
  * `logs/provider/events.log`: Provider event logs
  * `keybindings.json`: Keybindings configuration
</ParamField>

<ParamField path="staticDir" type="string | undefined">
  Static web asset directory for serving the React UI

  Auto-resolved from bundled client or monorepo build output. Set to `undefined` when using `devUrl`.
</ParamField>

<ParamField path="devUrl" type="URL | undefined">
  Development server URL for proxying/redirecting requests

  Set via `VITE_DEV_SERVER_URL` environment variable in development.
</ParamField>

<ParamField path="noBrowser" type="boolean" required>
  Disable automatic browser opening on startup

  Defaults to `true` in desktop mode, `false` in web mode.
</ParamField>

<ParamField path="authToken" type="string | undefined">
  Authentication token required for WebSocket connections

  When set, clients must provide this token to establish connections.
</ParamField>

<ParamField path="autoBootstrapProjectFromCwd" type="boolean" required>
  Automatically create a project for the current working directory on startup if missing

  Defaults to `true` in web mode, `false` in desktop mode.
</ParamField>

<ParamField path="logWebSocketEvents" type="boolean" required>
  Enable server-side logging of outbound WebSocket push traffic

  Defaults to `true` when `devUrl` is set.
</ParamField>

<ParamField path="keybindingsConfigPath" type="string" required>
  Path to keybindings configuration file

  Derived from `stateDir`: `{stateDir}/keybindings.json`
</ParamField>

## CliConfig

Startup-only service providing bootstrap helpers used during server layer construction.

**Service Tag:** `t3/main/CliConfig`

**Source:** `apps/server/src/main.ts:70`

### CliConfigShape

<ParamField path="cwd" type="string" required>
  Current process working directory
</ParamField>

<ParamField path="fixPath" type="Effect<void>" required>
  Apply OS-specific PATH normalization

  Ensures correct binary resolution on macOS and other platforms.
</ParamField>

<ParamField path="resolveStaticDir" type="Effect<string | undefined>" required>
  Resolve static web asset directory for server mode

  Searches in order:

  1. Bundled client: `{dirname}/client/index.html`
  2. Monorepo build: `../../web/dist/index.html`

  Returns `undefined` if no valid bundle is found.
</ParamField>

## Environment Variables

The server configuration can be controlled via environment variables:

<ParamField path="T3CODE_MODE" type="string">
  Runtime mode: `"web"` or `"desktop"`

  CLI flag: `--mode`
</ParamField>

<ParamField path="T3CODE_PORT" type="number">
  Server port (1-65535)

  CLI flag: `--port`
</ParamField>

<ParamField path="T3CODE_HOST" type="string">
  Host interface to bind

  CLI flag: `--host`
</ParamField>

<ParamField path="T3CODE_STATE_DIR" type="string">
  State directory path

  CLI flag: `--state-dir`
</ParamField>

<ParamField path="VITE_DEV_SERVER_URL" type="URL">
  Development web server URL

  CLI flag: `--dev-url`
</ParamField>

<ParamField path="T3CODE_NO_BROWSER" type="boolean">
  Disable automatic browser opening

  CLI flag: `--no-browser`
</ParamField>

<ParamField path="T3CODE_AUTH_TOKEN" type="string">
  WebSocket authentication token

  CLI flag: `--auth-token` or `--token`
</ParamField>

<ParamField path="T3CODE_AUTO_BOOTSTRAP_PROJECT_FROM_CWD" type="boolean">
  Auto-create project from working directory

  CLI flag: `--auto-bootstrap-project-from-cwd`
</ParamField>

<ParamField path="T3CODE_LOG_WS_EVENTS" type="boolean">
  Enable WebSocket event logging

  CLI flag: `--log-websocket-events` or `--log-ws-events`
</ParamField>

## CLI Usage

```bash theme={null}
# Start in web mode with dynamic port
t3 --mode web

# Start in desktop mode with fixed port
t3 --mode desktop --port 3773

# Bind to specific interface
t3 --host 127.0.0.1

# Use custom state directory
t3 --state-dir ~/.t3code

# Development mode with Vite dev server
t3 --dev-url http://localhost:5173

# Enable authentication
t3 --auth-token my-secret-token

# Disable browser auto-open
t3 --no-browser

# Enable WebSocket event logging
t3 --log-ws-events
```

## Configuration Resolution

Configuration values are resolved in the following priority order (highest to lowest):

1. **CLI Flags**: Explicit command-line arguments
2. **Environment Variables**: `T3CODE_*` prefixed variables
3. **Mode Defaults**: Defaults based on `--mode` setting
4. **Built-in Defaults**: Hardcoded fallback values

## Example Layer Construction

```typescript theme={null}
import { Layer, Effect } from "effect";
import { ServerConfig } from "./config";

// Test layer with explicit configuration
const testLayer = ServerConfig.layerTest(
  "/workspace",
  "/tmp/state"
);

// Use configuration in a program
const program = Effect.gen(function* () {
  const config = yield* ServerConfig;
  console.log(`Server running on port ${config.port}`);
  console.log(`State directory: ${config.stateDir}`);
}).pipe(Effect.provide(testLayer));
```

## Static Utilities

### resolveStaticDir

**Source:** `apps/server/src/config.ts:62`

Resolve the static web asset directory by searching for bundled or monorepo builds.

```typescript theme={null}
import { resolveStaticDir } from "./config";

const program = Effect.gen(function* () {
  const staticDir = yield* resolveStaticDir();
  if (staticDir) {
    console.log(`Serving static files from: ${staticDir}`);
  } else {
    console.warn("No static bundle found");
  }
});
```

**Returns:** `Effect<string | undefined>`

## Constants

<ResponseField name="DEFAULT_PORT" type="number">
  Default server port: `3773`

  **Source:** `apps/server/src/config.ts:11`
</ResponseField>

## Type Definitions

```typescript theme={null}
type RuntimeMode = "web" | "desktop";
```