Server Options

CLI flags and server configuration options for T3 Code

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: --token

Environment 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-events

Environment 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

Configuration	Default Value	Desktop Mode Default
Mode	web	desktop
Port	3773	3773
Host	undefined (all interfaces)	127.0.0.1
State Directory	~/.t3/userdata	~/.t3/userdata
No Browser	false	true
Auth Token	undefined	undefined
Auto Bootstrap	true	false
Log WebSocket Events	false	false

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.

Related

Environment Variables

Complete list of environment variables

Keybindings

Customize keyboard shortcuts