Environment Variables

T3 Code can be configured using environment variables. These are particularly useful for:

Docker deployments
CI/CD pipelines
System-wide configuration
Desktop app internal configuration

CLI flags take precedence over environment variables. See Server Options for CLI flag documentation.

Server Configuration

T3CODE_MODE

'web' | 'desktop'

default:"web"

Sets the runtime mode.

web: Network mode with dynamic port allocation
desktop: Secure loopback mode for desktop app

T3CODE_MODE=desktop npx t3

T3CODE_PORT

number

default:"3773"

Port number for the HTTP/WebSocket server (1-65535).

T3CODE_PORT=8080 npx t3

T3CODE_HOST

string

default:"undefined | 127.0.0.1 (desktop mode)"

Network interface or IP address to bind to.Examples:

127.0.0.1 - Local connections only
0.0.0.0 - All IPv4 interfaces
:: - All IPv6 interfaces
Specific IP (e.g., 192.168.1.100)

T3CODE_HOST=0.0.0.0 npx t3

T3CODE_STATE_DIR

string

default:"~/.t3/userdata"

Directory for storing state, database, and configuration files.

T3CODE_STATE_DIR=/custom/path npx t3

T3CODE_NO_BROWSER

boolean

default:"false | true (desktop mode)"

Disable automatic browser opening on startup.

T3CODE_NO_BROWSER=true npx t3

T3CODE_AUTH_TOKEN

string

default:"undefined"

Authentication token for WebSocket connections.

T3CODE_AUTH_TOKEN=your-secret-token npx t3

Never commit auth tokens to version control. Use secrets management for production deployments.

T3CODE_AUTO_BOOTSTRAP_PROJECT_FROM_CWD

boolean

default:"true (web) | false (desktop)"

Automatically create a project for the current working directory on startup.

T3CODE_AUTO_BOOTSTRAP_PROJECT_FROM_CWD=true npx t3

T3CODE_LOG_WS_EVENTS

boolean

default:"false | true (if VITE_DEV_SERVER_URL set)"

Enable verbose logging for WebSocket events.

T3CODE_LOG_WS_EVENTS=true npx t3

Development Variables

VITE_DEV_SERVER_URL

URL

default:"undefined"

Development server URL for proxying to Vite dev server.Used during T3 Code development to enable hot module replacement. Not needed for normal usage.

VITE_DEV_SERVER_URL=http://localhost:5173 npx t3

T3CODE_DEV_INSTANCE

string

default:"undefined"

Instance identifier for development mode.When set, automatically shifts all ports by a deterministic offset based on the instance name. This allows running multiple development instances without port conflicts.

# Each instance gets unique ports
T3CODE_DEV_INSTANCE=feature-a bun run dev:desktop
T3CODE_DEV_INSTANCE=feature-b bun run dev:desktop

T3CODE_DEV_INSTANCE is used by T3 Code’s development scripts. It hashes the instance name to generate a port offset.

T3CODE_PORT_OFFSET

number

default:"0"

Numeric port offset for development mode.Provides manual control over port shifting instead of using the hashed offset from T3CODE_DEV_INSTANCE.

T3CODE_PORT_OFFSET=100 bun run dev:desktop

Desktop App Variables

These variables are used internally by the desktop app and typically don’t need manual configuration.

T3CODE_DESKTOP_WS_URL

URL

default:"undefined"

WebSocket URL for desktop app to connect to the backend server.Automatically set by the desktop app during startup.

T3CODE_DESKTOP_UPDATE_GITHUB_TOKEN

string

default:"undefined"

GitHub token for accessing update releases.Used for accessing updates from private repositories during development.

T3CODE_DISABLE_AUTO_UPDATE

'1' | undefined

default:"undefined"

Disable automatic updates in the desktop app.Set to 1 to disable auto-updates.

T3CODE_DISABLE_AUTO_UPDATE=1 ./t3-code

T3CODE_COMMIT_HASH

string

default:"undefined"

Git commit hash for version tracking.Automatically set during build. Used by the updater to determine the current version.

Docker Example

Configuration via environment variables is ideal for containerized deployments:

docker-compose.yml

version: '3.8'
services:
  t3code:
    image: t3code:latest
    environment:
      T3CODE_MODE: web
      T3CODE_PORT: 3773
      T3CODE_HOST: 0.0.0.0
      T3CODE_STATE_DIR: /data
      T3CODE_NO_BROWSER: true
      T3CODE_AUTH_TOKEN: ${T3CODE_AUTH_TOKEN}
    ports:
      - "3773:3773"
    volumes:
      - ./data:/data
      - ./workspace:/workspace

CI/CD Example

.github/workflows/test.yml

name: Test
on: [push]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Start T3 Code
        env:
          T3CODE_NO_BROWSER: true
          T3CODE_AUTO_BOOTSTRAP_PROJECT_FROM_CWD: false
          T3CODE_STATE_DIR: /tmp/t3-state
        run: |
          npx t3 &
          sleep 5
      - name: Run tests
        run: npm test

Systemd Service Example

/etc/systemd/system/t3code.service

[Unit]
Description=T3 Code Server
After=network.target

[Service]
Type=simple
User=t3code
WorkingDirectory=/home/t3code/workspace
Environment="T3CODE_MODE=web"
Environment="T3CODE_PORT=3773"
Environment="T3CODE_HOST=0.0.0.0"
Environment="T3CODE_STATE_DIR=/var/lib/t3code"
Environment="T3CODE_NO_BROWSER=true"
Environment="T3CODE_AUTH_TOKEN=your-secret-token"
ExecStart=/usr/bin/npx t3
Restart=always

[Install]
WantedBy=multi-user.target

Security Best Practices

Authentication Tokens

Use strong, randomly generated tokens
Store tokens in secrets management systems
Rotate tokens periodically
Never commit tokens to version control
Use different tokens for different environments

Network Binding

Use 127.0.0.1 for local-only access
Use 0.0.0.0 with authentication for remote access
Consider using a reverse proxy (nginx, Caddy) with HTTPS
Use firewall rules to restrict access

State Directory

Set appropriate filesystem permissions
Keep state directory outside web root
Back up state directory regularly
Use separate state directories for different environments

Troubleshooting

Port Already in Use

# Check what's using the port
lsof -i :3773

# Use a different port
T3CODE_PORT=3774 npx t3

Permission Denied for State Directory

# Check permissions
ls -la ~/.t3

# Fix permissions
chmod 700 ~/.t3

# Or use a different directory
T3CODE_STATE_DIR=/tmp/t3-state npx t3

Cannot Connect Remotely

# Ensure binding to correct interface
T3CODE_HOST=0.0.0.0 npx t3

# Check firewall
sudo ufw allow 3773

Server Options

CLI flags and detailed configuration

Keybindings

Customize keyboard shortcuts

Get Started

Core Concepts

Usage Guides

Configuration

Development

Environment Variables

Server Configuration

T3CODE_MODE

T3CODE_PORT

T3CODE_HOST

T3CODE_STATE_DIR

T3CODE_NO_BROWSER

T3CODE_AUTH_TOKEN

T3CODE_AUTO_BOOTSTRAP_PROJECT_FROM_CWD

T3CODE_LOG_WS_EVENTS

Development Variables

VITE_DEV_SERVER_URL

T3CODE_DEV_INSTANCE

T3CODE_PORT_OFFSET

Desktop App Variables

T3CODE_DESKTOP_WS_URL

T3CODE_DESKTOP_UPDATE_GITHUB_TOKEN

T3CODE_DISABLE_AUTO_UPDATE

T3CODE_COMMIT_HASH

Docker Example

CI/CD Example

Systemd Service Example

Security Best Practices

Troubleshooting

Port Already in Use

Permission Denied for State Directory

Cannot Connect Remotely

Server Options

Keybindings

Build docs developers (and LLMs) love

Get Started

Core Concepts

Usage Guides

Configuration

Development

​Server Configuration

​T3CODE_MODE

​T3CODE_PORT

​T3CODE_HOST

​T3CODE_STATE_DIR

​T3CODE_NO_BROWSER

​T3CODE_AUTH_TOKEN

​T3CODE_AUTO_BOOTSTRAP_PROJECT_FROM_CWD

​T3CODE_LOG_WS_EVENTS

​Development Variables

​VITE_DEV_SERVER_URL

​T3CODE_DEV_INSTANCE

​T3CODE_PORT_OFFSET

​Desktop App Variables

​T3CODE_DESKTOP_WS_URL

​T3CODE_DESKTOP_UPDATE_GITHUB_TOKEN

​T3CODE_DISABLE_AUTO_UPDATE

​T3CODE_COMMIT_HASH

​Docker Example

​CI/CD Example

​Systemd Service Example

​Security Best Practices

​Troubleshooting

​Port Already in Use

​Permission Denied for State Directory

​Cannot Connect Remotely

​Related

Server Options

Keybindings

Build docs developers (and LLMs) love

Server Configuration

T3CODE_MODE

T3CODE_PORT

T3CODE_HOST

T3CODE_STATE_DIR

T3CODE_NO_BROWSER

T3CODE_AUTH_TOKEN

T3CODE_AUTO_BOOTSTRAP_PROJECT_FROM_CWD

T3CODE_LOG_WS_EVENTS

Development Variables

VITE_DEV_SERVER_URL

T3CODE_DEV_INSTANCE

T3CODE_PORT_OFFSET

Desktop App Variables

T3CODE_DESKTOP_WS_URL

T3CODE_DESKTOP_UPDATE_GITHUB_TOKEN

T3CODE_DISABLE_AUTO_UPDATE

T3CODE_COMMIT_HASH

Docker Example

CI/CD Example

Systemd Service Example

Security Best Practices

Troubleshooting

Port Already in Use

Permission Denied for State Directory

Cannot Connect Remotely

Related