Skip to main content

​
Overview

The T3 Code CLI provides powerful options for running the server with custom configurations. Use it for development, production deployments, remote access, and CI/CD integration.

​
Basic Usage

Start the server with default settings: 
t3
This starts the server on the first available port (starting at 8080) and opens your default browser.

​
CLI Flags

​
Mode

Set the runtime mode: 
# Web mode (default) - serves web UI
t3 --mode web

# Desktop mode - optimized for Electron app
t3 --mode desktop
Desktop mode differences:
  • Binds to 127.0.0.1 by default (security)
  • Disables automatic browser opening
  • Uses fixed port (8080)

​
Port

Specify the HTTP/WebSocket server port: 
# Custom port
t3 --port 3000

# Port must be between 1-65535
t3 --port 8080
In web mode, if the port is taken, the server finds the next available port. In desktop mode, it fails if the port is occupied.

​
Host

Bind to a specific network interface: 
# Localhost only (default in desktop mode)
t3 --host 127.0.0.1

# All interfaces (remote access)
t3 --host 0.0.0.0

# Specific IP (e.g., Tailnet)
t3 --host 100.64.1.2

# IPv6
t3 --host '[::]'
Binding to 0.0.0.0 or [::] exposes the server to your network. Use --auth-token for security.

​
State Directory

Customize where T3 Code stores data: 
# Custom state directory
t3 --state-dir ~/.t3-custom

# Project-specific state
t3 --state-dir ./t3-state
State directory contains:
  • SQLite database (projects, threads, messages)
  • keybindings.json configuration
  • Checkpoint metadata
  • Session state
Default locations:
  • macOS: ~/Library/Application Support/T3 Code
  • Windows: %APPDATA%\T3 Code
  • Linux: ~/.config/t3-code

​
Development URL

Proxy to a Vite dev server during development: 
# Proxy to local Vite server
t3 --dev-url http://localhost:5173

# Custom dev server port
t3 --dev-url http://localhost:3000
Useful when developing the web interface.

​
Browser Control

Disable automatic browser opening: 
# Don't open browser
t3 --no-browser

# Useful for server-only deployments
t3 --no-browser --host 0.0.0.0

​
Authentication

Require a token for WebSocket connections: 
# Set auth token
t3 --auth-token secret123

# Generate secure token
t3 --auth-token $(openssl rand -hex 32)
The web interface must provide this token in the WebSocket URL: 
ws://localhost:8080?token=secret123
Auth tokens are essential when binding to non-localhost interfaces.

​
Project Bootstrapping

Automatically create a project for the current directory: 
# Auto-create project from cwd
t3 --auto-bootstrap-project-from-cwd

# Default enabled in web mode, disabled in desktop mode
The server creates a project named after the directory and starts a thread.

​
WebSocket Logging

Enable detailed WebSocket event logging: 
# Log all WebSocket events
t3 --log-websocket-events

# Short alias
t3 --log-ws-events
Useful for debugging connection issues and event flow.

​
Environment Variables

All flags have environment variable equivalents: 
# Mode
export T3CODE_MODE=web

# Port
export T3CODE_PORT=3000

# Host
export T3CODE_HOST=0.0.0.0

# State directory
export T3CODE_STATE_DIR=~/.t3-custom

# Dev URL
export VITE_DEV_SERVER_URL=http://localhost:5173

# No browser
export T3CODE_NO_BROWSER=true

# Auth token
export T3CODE_AUTH_TOKEN=secret123

# Auto-bootstrap
export T3CODE_AUTO_BOOTSTRAP_PROJECT_FROM_CWD=true

# WebSocket logging
export T3CODE_LOG_WS_EVENTS=true
CLI flags override environment variables.

​
Common Scenarios

​
Local Development

# Default setup
t3

# With dev server
t3 --dev-url http://localhost:5173

# Custom port with logging
t3 --port 3000 --log-ws-events

​
Remote Access

1

Bind to all interfaces

t3 --host 0.0.0.0 --port 8080
2

Add authentication

t3 --host 0.0.0.0 --auth-token $(openssl rand -hex 32)
3

Share the URL

echo "Connect to: http://YOUR_IP:8080?token=YOUR_TOKEN"

​
Tailscale Setup

# Get your Tailnet IP
tailscale ip -4

# Bind to Tailnet interface
t3 --host 100.64.1.2 --port 8080 --auth-token secure123
Access from any device on your Tailnet: 
http://100.64.1.2:8080?token=secure123

​
Production Deployment

# Production settings
t3 \
  --mode web \
  --host 0.0.0.0 \
  --port 8080 \
  --no-browser \
  --auth-token $AUTH_TOKEN \
  --state-dir /var/lib/t3-code

​
Docker Container

FROM node:20-slim

WORKDIR /app
COPY . .
RUN bun install && bun run build

ENV T3CODE_HOST=0.0.0.0
ENV T3CODE_PORT=8080
ENV T3CODE_NO_BROWSER=true
ENV T3CODE_STATE_DIR=/data

EXPOSE 8080
VOLUME /data

CMD ["t3"]
Run: 
docker run -p 8080:8080 -v t3-data:/data t3-code

​
Systemd Service

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

[Service]
Type=simple
User=t3code
WorkingDirectory=/opt/t3-code
Environment="T3CODE_HOST=0.0.0.0"
Environment="T3CODE_PORT=8080"
Environment="T3CODE_NO_BROWSER=true"
Environment="T3CODE_AUTH_TOKEN=YOUR_TOKEN"
Environment="T3CODE_STATE_DIR=/var/lib/t3-code"
ExecStart=/usr/local/bin/t3
Restart=on-failure

[Install]
WantedBy=multi-user.target
Enable and start: 
sudo systemctl enable t3-code
sudo systemctl start t3-code

​
Security Best Practices

Always use authentication when exposing the server beyond localhost.

​
Generate Strong Tokens

# OpenSSL
openssl rand -hex 32

# Node.js
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

# Python
python -c "import secrets; print(secrets.token_hex(32))"

​
Restrict Network Access

Use firewall rules to limit connections: 
# Allow only specific IPs
sudo ufw allow from 192.168.1.0/24 to any port 8080

# Deny all others
sudo ufw deny 8080

​
Use Reverse Proxy

Run behind nginx or Caddy for HTTPS: 
server {
  listen 443 ssl;
  server_name t3.example.com;
  
  ssl_certificate /path/to/cert.pem;
  ssl_certificate_key /path/to/key.pem;
  
  location / {
    proxy_pass http://localhost:8080;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
  }
}

​
Debugging

​
Verbose Logging

Enable debug logs: 
# Enable WebSocket event logging
t3 --log-ws-events

# Check server logs
tail -f ~/.config/t3-code/server.log

​
Connection Issues

Test WebSocket connection: 
# Using websocat
websocat ws://localhost:8080

# With authentication
websocat "ws://localhost:8080?token=secret123"

​
Port Conflicts

Find process using a port: 
# macOS/Linux
lsof -i :8080

# Windows
netstat -ano | findstr :8080
Kill the conflicting process or choose a different port.

​
Performance Tuning

​
State Directory on SSD

Store state on fast storage for better database performance: 
t3 --state-dir /mnt/nvme/t3-state

​
Limit Concurrent Sessions

The server handles multiple projects and threads efficiently, but heavy workloads benefit from dedicated resources:
  • Light use (1-2 active threads): 2GB RAM, 2 CPU cores
  • Medium use (3-5 active threads): 4GB RAM, 4 CPU cores
  • Heavy use (6+ active threads): 8GB RAM, 8 CPU cores

​
Next Steps