> ## 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.

# 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

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

<ParamField path="--mode" type="'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`
</ParamField>

### Network Configuration

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

  ```bash theme={null}
  # Custom port
  npx t3 --port 8080
  ```
</ParamField>

<ParamField path="--host" type="string" default="undefined (all interfaces) | 127.0.0.1 (desktop mode)">
  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`

  ```bash theme={null}
  # Bind to specific interface
  npx t3 --host 127.0.0.1

  # Bind to all interfaces
  npx t3 --host 0.0.0.0
  ```
</ParamField>

### State and Storage

<ParamField path="--state-dir" type="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`

  ```bash theme={null}
  # Custom state directory
  npx t3 --state-dir /path/to/state
  ```
</ParamField>

### Browser Control

<ParamField path="--no-browser" type="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`

  ```bash theme={null}
  # Don't open browser
  npx t3 --no-browser
  ```
</ParamField>

### Authentication

<ParamField path="--auth-token" type="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`

  ```bash theme={null}
  # Require authentication
  npx t3 --auth-token your-secret-token
  ```
</ParamField>

<Warning>
  Keep your auth token secret. Anyone with the token can connect to your T3 Code server.
</Warning>

### Project Management

<ParamField path="--auto-bootstrap-project-from-cwd" type="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`

  ```bash theme={null}
  # Disable auto-bootstrap
  npx t3 --auto-bootstrap-project-from-cwd=false
  ```
</ParamField>

### Development Options

<ParamField path="--dev-url" type="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`

  ```bash theme={null}
  # Connect to Vite dev server
  npx t3 --dev-url http://localhost:5173
  ```
</ParamField>

<Note>
  The `--dev-url` flag is primarily for T3 Code development. Most users won't need this.
</Note>

<ParamField path="--log-websocket-events" type="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`

  ```bash theme={null}
  # Enable WebSocket logging
  npx t3 --log-websocket-events
  ```
</ParamField>

## 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

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

```bash theme={null}
# Start with defaults
npx t3
```

### Remote Access

```bash theme={null}
# Bind to all interfaces with authentication
npx t3 --host 0.0.0.0 --auth-token your-secret-token
```

### Multiple Instances

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

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

<CardGroup cols={2}>
  <Card title="Environment Variables" icon="code" href="/configuration/environment-variables">
    Complete list of environment variables
  </Card>

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