Environment Variables

Environment variables for configuring T3 Code server behavior

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

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

T3CODE_PORT · number · default: "3773"

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

T3CODE_PORT=8080 npx t3

T3CODE_HOST

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

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

T3CODE_NO_BROWSER · boolean · default: "false | true (desktop mode)"

Disable automatic browser opening on startup.

T3CODE_NO_BROWSER=true npx t3

T3CODE_AUTH_TOKEN

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

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

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

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

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

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

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

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

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

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

Related

Server Options

CLI flags and detailed configuration

Keybindings

Customize keyboard shortcuts