> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/pingdotgg/t3code/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<Note>
  CLI flags take precedence over environment variables. See [Server Options](/configuration/server-options) for CLI flag documentation.
</Note>

## Server Configuration

### T3CODE\_MODE

<ParamField path="T3CODE_MODE" type="'web' | 'desktop'" default="web">
  Sets the runtime mode.

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

  ```bash theme={null}
  T3CODE_MODE=desktop npx t3
  ```
</ParamField>

### T3CODE\_PORT

<ParamField path="T3CODE_PORT" type="number" default="3773">
  Port number for the HTTP/WebSocket server (1-65535).

  ```bash theme={null}
  T3CODE_PORT=8080 npx t3
  ```
</ParamField>

### T3CODE\_HOST

<ParamField path="T3CODE_HOST" type="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`)

  ```bash theme={null}
  T3CODE_HOST=0.0.0.0 npx t3
  ```
</ParamField>

### T3CODE\_STATE\_DIR

<ParamField path="T3CODE_STATE_DIR" type="string" default="~/.t3/userdata">
  Directory for storing state, database, and configuration files.

  ```bash theme={null}
  T3CODE_STATE_DIR=/custom/path npx t3
  ```
</ParamField>

### T3CODE\_NO\_BROWSER

<ParamField path="T3CODE_NO_BROWSER" type="boolean" default="false | true (desktop mode)">
  Disable automatic browser opening on startup.

  ```bash theme={null}
  T3CODE_NO_BROWSER=true npx t3
  ```
</ParamField>

### T3CODE\_AUTH\_TOKEN

<ParamField path="T3CODE_AUTH_TOKEN" type="string" default="undefined">
  Authentication token for WebSocket connections.

  ```bash theme={null}
  T3CODE_AUTH_TOKEN=your-secret-token npx t3
  ```
</ParamField>

<Warning>
  Never commit auth tokens to version control. Use secrets management for production deployments.
</Warning>

### T3CODE\_AUTO\_BOOTSTRAP\_PROJECT\_FROM\_CWD

<ParamField path="T3CODE_AUTO_BOOTSTRAP_PROJECT_FROM_CWD" type="boolean" default="true (web) | false (desktop)">
  Automatically create a project for the current working directory on startup.

  ```bash theme={null}
  T3CODE_AUTO_BOOTSTRAP_PROJECT_FROM_CWD=true npx t3
  ```
</ParamField>

### T3CODE\_LOG\_WS\_EVENTS

<ParamField path="T3CODE_LOG_WS_EVENTS" type="boolean" default="false | true (if VITE_DEV_SERVER_URL set)">
  Enable verbose logging for WebSocket events.

  ```bash theme={null}
  T3CODE_LOG_WS_EVENTS=true npx t3
  ```
</ParamField>

## Development Variables

### VITE\_DEV\_SERVER\_URL

<ParamField path="VITE_DEV_SERVER_URL" type="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.

  ```bash theme={null}
  VITE_DEV_SERVER_URL=http://localhost:5173 npx t3
  ```
</ParamField>

### T3CODE\_DEV\_INSTANCE

<ParamField path="T3CODE_DEV_INSTANCE" type="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.

  ```bash theme={null}
  # Each instance gets unique ports
  T3CODE_DEV_INSTANCE=feature-a bun run dev:desktop
  T3CODE_DEV_INSTANCE=feature-b bun run dev:desktop
  ```
</ParamField>

<Note>
  `T3CODE_DEV_INSTANCE` is used by T3 Code's development scripts. It hashes the instance name to generate a port offset.
</Note>

### T3CODE\_PORT\_OFFSET

<ParamField path="T3CODE_PORT_OFFSET" type="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`.

  ```bash theme={null}
  T3CODE_PORT_OFFSET=100 bun run dev:desktop
  ```
</ParamField>

## Desktop App Variables

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

### T3CODE\_DESKTOP\_WS\_URL

<ParamField path="T3CODE_DESKTOP_WS_URL" type="URL" default="undefined">
  WebSocket URL for desktop app to connect to the backend server.

  Automatically set by the desktop app during startup.
</ParamField>

### T3CODE\_DESKTOP\_UPDATE\_GITHUB\_TOKEN

<ParamField path="T3CODE_DESKTOP_UPDATE_GITHUB_TOKEN" type="string" default="undefined">
  GitHub token for accessing update releases.

  Used for accessing updates from private repositories during development.
</ParamField>

### T3CODE\_DISABLE\_AUTO\_UPDATE

<ParamField path="T3CODE_DISABLE_AUTO_UPDATE" type="'1' | undefined" default="undefined">
  Disable automatic updates in the desktop app.

  Set to `1` to disable auto-updates.

  ```bash theme={null}
  T3CODE_DISABLE_AUTO_UPDATE=1 ./t3-code
  ```
</ParamField>

### T3CODE\_COMMIT\_HASH

<ParamField path="T3CODE_COMMIT_HASH" type="string" default="undefined">
  Git commit hash for version tracking.

  Automatically set during build. Used by the updater to determine the current version.
</ParamField>

## Docker Example

Configuration via environment variables is ideal for containerized deployments:

```yaml docker-compose.yml theme={null}
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

```yaml .github/workflows/test.yml theme={null}
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

```ini /etc/systemd/system/t3code.service theme={null}
[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

<AccordionGroup>
  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="State Directory">
    * Set appropriate filesystem permissions
    * Keep state directory outside web root
    * Back up state directory regularly
    * Use separate state directories for different environments
  </Accordion>
</AccordionGroup>

## Troubleshooting

### Port Already in Use

```bash theme={null}
# Check what's using the port
lsof -i :3773

# Use a different port
T3CODE_PORT=3774 npx t3
```

### Permission Denied for State Directory

```bash theme={null}
# 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

```bash theme={null}
# Ensure binding to correct interface
T3CODE_HOST=0.0.0.0 npx t3

# Check firewall
sudo ufw allow 3773
```

## Related

<CardGroup cols={2}>
  <Card title="Server Options" icon="terminal" href="/configuration/server-options">
    CLI flags and detailed configuration
  </Card>

  <Card title="Keybindings" icon="keyboard" href="/configuration/keybindings">
    Customize keyboard shortcuts
  </Card>
</CardGroup>