# Environment Variables

Complete reference of all environment variables supported by Windshift. These can also be set via CLI flags - see [Configuration Options](/docs/03-configuration/01-options) for the flag equivalents.

## Core

| Variable | Default | Description |
|----------|---------|-------------|
| `PORT` | `8080` | HTTP server port |
| `BASE_URL` | - | Public URL for Windshift (used in emails, SSO redirects) |
| `SSO_SECRET` | - | Secret key for SSO state and session cookie encryption (generate with `openssl rand -hex 32`) |

## Database

| Variable | Default | Description |
|----------|---------|-------------|
| `DB_PATH` | `windshift.db` | SQLite database file path |
| `DB_TYPE` | - | Database type override |
| `POSTGRES_CONNECTION_STRING` | - | PostgreSQL connection string (overrides SQLite) |
| `MAX_READ_CONNS` | `120` | Maximum SQLite read connections |
| `MAX_WRITE_CONNS` | `1` | Maximum SQLite write connections |

## Files

| Variable | Default | Description |
|----------|---------|-------------|
| `ATTACHMENT_PATH` | - | Directory for uploaded file attachments |

## Proxy & Security

| Variable | Default | Description |
|----------|---------|-------------|
| `USE_PROXY` | `false` | Trust reverse proxy headers (X-Forwarded-Proto, X-Forwarded-For) |
| `ALLOWED_HOSTS` | - | Comma-separated list of valid hostnames for request validation |
| `ADDITIONAL_PROXIES` | - | Additional trusted proxy IP addresses beyond the default private ranges |

## SSH / TUI

| Variable | Default | Description |
|----------|---------|-------------|
| `SSH_ENABLED` | `false` | Enable SSH TUI server |
| `SSH_PORT` | `23234` | SSH server port |
| `SSH_HOST` | `localhost` | SSH server bind address |

## Logging

| Variable | Default | Description |
|----------|---------|-------------|
| `LOG_LEVEL` | `info` | Log level: `debug`, `info`, `warn`, `error` |
| `LOG_FORMAT` | `text` | Log format: `text`, `json`, `logfmt` |

## Plugins

| Variable | Default | Description |
|----------|---------|-------------|
| `DISABLE_PLUGINS` | `false` | Disable the plugin system entirely |

## Authentication

| Variable | Default | Description |
|----------|---------|-------------|
| `ENABLE_ADMIN_FALLBACK` | `false` | Enable password-based admin login when SSO is the only auth method |

## AI & Services

| Variable | Default | Description |
|----------|---------|-------------|
| `LLM_ENDPOINT` | - | URL for the LLM inference service |
| `LLM_PROVIDERS_FILE` | - | Path to a custom LLM providers JSON configuration |
| `LOGBOOK_ENDPOINT` | - | URL for the Logbook knowledge management service |

## Docker Compose Template

A typical `.env` file for Docker Compose:

```bash
# Required
DOMAIN=windshift.example.com
PORT=8080
SSO_SECRET=your-generated-secret-here

# PostgreSQL (only if using PostgreSQL)
POSTGRES_PASSWORD=secure-database-password

# Traefik (only if using Traefik for HTTPS)
LETSENCRYPT_EMAIL=admin@example.com

# LLM (only if using local LLM inference)
LLM_THREADS=4
```

## Using Varlock for Configuration Management

[Varlock](https://varlock.dev) is an optional CLI tool that adds schema-based validation and secret leak prevention to your `.env` files. It works as a drop-in wrapper — your existing `.env` files stay the same.

### Install

```bash
# macOS
brew install dmno-dev/tap/varlock

# Linux / CI
curl -sSfL https://varlock.dev/install.sh | sh -s
```

### Initialize

Run `varlock init` in your project directory. It reads your existing `.env` files and generates a `.env.schema`:

```bash
cd /path/to/windshift
varlock init
```

### Example `.env.schema`

```bash
# @required @sensitive @type=string
SSO_SECRET=

# @required @type=url
# @example="https://windshift.example.com"
BASE_URL=

# @type=port @optional
PORT=8080

# @sensitive @optional
POSTGRES_PASSWORD=

# @optional @type=email
LETSENCRYPT_EMAIL=
```

The decorators (`@required`, `@sensitive`, `@type`) document each variable's constraints. Varlock uses them to catch misconfigurations before your services start.

### Validate

Check your configuration without starting anything:

```bash
varlock load
```

This reports missing required variables, type mismatches, and other schema violations.

### Run with Validation

Validate and inject variables in one step:

```bash
varlock run -- docker compose up -d
```

This ensures every required variable is set and correctly typed before Docker Compose starts.