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

mode · RuntimeMode · required

Runtime mode: "web" or "desktop"

• web: Production mode with dynamic port allocation
• desktop: Loopback-only mode with fixed defaults

port · number · required

HTTP/WebSocket server port (1-65535)

Defaults to 3773 in desktop mode, or dynamically allocated in web mode.

host · 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

cwd · string · required

Current working directory of the server process

stateDir · 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

staticDir · 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.

devUrl · URL | undefined

Development server URL for proxying/redirecting requests

Set via VITE_DEV_SERVER_URL environment variable in development.

noBrowser · boolean · required

Disable automatic browser opening on startup

Defaults to true in desktop mode, false in web mode.

authToken · string | undefined

Authentication token required for WebSocket connections

When set, clients must provide this token to establish connections.

autoBootstrapProjectFromCwd · 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.

logWebSocketEvents · boolean · required

Enable server-side logging of outbound WebSocket push traffic

Defaults to true when devUrl is set.

keybindingsConfigPath · string · required

Path to keybindings configuration file

Derived from stateDir: {stateDir}/keybindings.json

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

cwd · string · required

Current process working directory

fixPath · Effect<void> · required

Apply OS-specific PATH normalization

Ensures correct binary resolution on macOS and other platforms.

resolveStaticDir · 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.

Environment Variables

The server configuration can be controlled via environment variables:

T3CODE_MODE · string

Runtime mode: "web" or "desktop"

CLI flag: --mode

T3CODE_PORT · number

Server port (1-65535)

CLI flag: --port

T3CODE_HOST · string

Host interface to bind

CLI flag: --host

T3CODE_STATE_DIR · string

State directory path

CLI flag: --state-dir

VITE_DEV_SERVER_URL · URL

Development web server URL

CLI flag: --dev-url

T3CODE_NO_BROWSER · boolean

Disable automatic browser opening

CLI flag: --no-browser

T3CODE_AUTH_TOKEN · string

WebSocket authentication token

CLI flag: --auth-token or --token

T3CODE_AUTO_BOOTSTRAP_PROJECT_FROM_CWD · boolean

Auto-create project from working directory

CLI flag: --auto-bootstrap-project-from-cwd

T3CODE_LOG_WS_EVENTS · boolean

Enable WebSocket event logging

CLI flag: --log-websocket-events or --log-ws-events

CLI Usage

# 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

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.

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

DEFAULT_PORT · number

Default server port: 3773

Source: apps/server/src/config.ts:11

Type Definitions

type RuntimeMode = "web" | "desktop";