Skip to main content

​
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 stateContains:
  • 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 UIAuto-resolved from bundled client or monorepo build output. Set to undefined when using devUrl.
​
devUrl
URL | undefined
Development server URL for proxying/redirecting requestsSet via VITE_DEV_SERVER_URL environment variable in development.
​
noBrowser
boolean
required
Disable automatic browser opening on startupDefaults to true in desktop mode, false in web mode.
​
authToken
string | undefined
Authentication token required for WebSocket connectionsWhen set, clients must provide this token to establish connections.
​
autoBootstrapProjectFromCwd
boolean
required
Automatically create a project for the current working directory on startup if missingDefaults to true in web mode, false in desktop mode.
​
logWebSocketEvents
boolean
required
Enable server-side logging of outbound WebSocket push trafficDefaults to true when devUrl is set.
​
keybindingsConfigPath
string
required
Path to keybindings configuration fileDerived 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 normalizationEnsures correct binary resolution on macOS and other platforms.
​
resolveStaticDir
Effect<string | undefined>
required
Resolve static web asset directory for server modeSearches 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 bindCLI flag: --host
​
T3CODE_STATE_DIR
string
State directory pathCLI flag: --state-dir
​
VITE_DEV_SERVER_URL
URL
Development web server URLCLI flag: --dev-url
​
T3CODE_NO_BROWSER
boolean
Disable automatic browser openingCLI flag: --no-browser
​
T3CODE_AUTH_TOKEN
string
WebSocket authentication tokenCLI flag: --auth-token or --token
​
T3CODE_AUTO_BOOTSTRAP_PROJECT_FROM_CWD
boolean
Auto-create project from working directoryCLI flag: --auto-bootstrap-project-from-cwd
​
T3CODE_LOG_WS_EVENTS
boolean
Enable WebSocket event loggingCLI 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: 3773Source: apps/server/src/config.ts:11

​
Type Definitions

type RuntimeMode = "web" | "desktop";