Skip to main content
T3 Code server accepts configuration through CLI flags and environment variables. CLI flags take precedence over environment variables.

​
Starting the Server

# Basic usage
npx t3

# With custom port
npx t3 --port 8080

# Desktop mode with authentication
npx t3 --mode desktop --auth-token your-secret-token

​
CLI Flags

​
Runtime Mode

​
--mode
'web' | 'desktop'
default:"web"
Runtime mode for the server.
  • web: Allows dynamic port allocation and network binding (default)
  • desktop: Uses loopback defaults (127.0.0.1) for security
Environment variable: T3CODE_MODE

​
Network Configuration

​
--port
number
default:"3773"
Port for the HTTP/WebSocket server. Must be between 1 and 65535.In web mode, if the port is unavailable, the server will automatically find an available port starting from the default.Environment variable: T3CODE_PORT
# Custom port
npx t3 --port 8080
​
--host
string
Host or network interface to bind the server to.Common values:
  • 127.0.0.1 - Loopback only (local connections)
  • 0.0.0.0 - All IPv4 interfaces
  • :: - All IPv6 interfaces
  • Specific IP address (e.g., Tailnet IP)
Environment variable: T3CODE_HOST
# Bind to specific interface
npx t3 --host 127.0.0.1

# Bind to all interfaces
npx t3 --host 0.0.0.0

​
State and Storage

​
--state-dir
string
default:"~/.t3/userdata"
Directory path for server state, database, and configuration files.The state directory contains:
  • SQLite database
  • Keybindings configuration
  • Session data
  • Logs
Environment variable: T3CODE_STATE_DIR
# Custom state directory
npx t3 --state-dir /path/to/state

​
Browser Control

​
--no-browser
boolean
default:"false (true in desktop mode)"
Disable automatic browser opening on server startup.By default, the server opens your default browser when starting in web mode. Desktop mode automatically sets this to true.Environment variable: T3CODE_NO_BROWSER
# Don't open browser
npx t3 --no-browser

​
Authentication

​
--auth-token
string
default:"undefined"
Authentication token required for WebSocket connections.When set, clients must provide this token to establish WebSocket connections. Useful for securing remote access.Alias: --tokenEnvironment variable: T3CODE_AUTH_TOKEN
# Require authentication
npx t3 --auth-token your-secret-token
Keep your auth token secret. Anyone with the token can connect to your T3 Code server.

​
Project Management

​
--auto-bootstrap-project-from-cwd
boolean
default:"true (web mode) | false (desktop mode)"
Automatically create a project for the current working directory on startup if one doesn’t exist.When enabled, T3 Code will create a project entry for the directory where you run the server.Environment variable: T3CODE_AUTO_BOOTSTRAP_PROJECT_FROM_CWD
# Disable auto-bootstrap
npx t3 --auto-bootstrap-project-from-cwd=false

​
Development Options

​
--dev-url
URL
default:"undefined"
Development web server URL to proxy or redirect to.Used during development to connect to a Vite dev server instead of serving static files. Enables hot module replacement and fast refresh.Environment variable: VITE_DEV_SERVER_URL
# Connect to Vite dev server
npx t3 --dev-url http://localhost:5173
The --dev-url flag is primarily for T3 Code development. Most users won’t need this.
​
--log-websocket-events
boolean
default:"false (true if dev-url is set)"
Emit server-side logs for outbound WebSocket push traffic.Useful for debugging WebSocket communication issues. Automatically enabled when using --dev-url.Alias: --log-ws-eventsEnvironment variable: T3CODE_LOG_WS_EVENTS
# Enable WebSocket logging
npx t3 --log-websocket-events

​
Configuration Precedence

Configuration is resolved in the following order (highest to lowest priority):
  1. CLI flags (e.g., --port 8080)
  2. Environment variables (e.g., T3CODE_PORT=8080)
  3. Default values
# CLI flag takes precedence
T3CODE_PORT=9000 npx t3 --port 8080
# Server will use port 8080

​
Default Values

ConfigurationDefault ValueDesktop Mode Default
Modewebdesktop
Port37733773
Hostundefined (all interfaces)127.0.0.1
State Directory~/.t3/userdata~/.t3/userdata
No Browserfalsetrue
Auth Tokenundefinedundefined
Auto Bootstraptruefalse
Log WebSocket Eventsfalsefalse

​
Common Configurations

​
Local Development

# Start with defaults
npx t3

​
Remote Access

# Bind to all interfaces with authentication
npx t3 --host 0.0.0.0 --auth-token your-secret-token

​
Multiple Instances

# Run multiple instances with different ports and state directories
npx t3 --port 3773 --state-dir ~/.t3/instance1
npx t3 --port 3774 --state-dir ~/.t3/instance2

​
CI/CD Environment

# Headless operation
npx t3 --no-browser --auto-bootstrap-project-from-cwd=false

​
Desktop App

The desktop app automatically configures:
  • --mode desktop
  • --no-browser
  • --host 127.0.0.1
  • --auth-token (automatically generated)
You don’t need to set these manually when using the desktop app.

Environment Variables

Complete list of environment variables

Keybindings

Customize keyboard shortcuts

Build docs developers (and LLMs) love

Get started for freeTalk to us