> For the complete documentation index, see [llms.txt](https://docs.controltheory.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.controltheory.com/controltheory-documentation/gonzo-docs/reference/environment-variables.md).

# Environment Variables

Complete reference for environment variables that configure Gonzo's behavior. Environment variables provide a convenient way to configure Gonzo without command-line flags or config files.

### Overview

Environment variables are useful for:

* **Container deployments**: Configure via Docker/Kubernetes env vars
* **CI/CD pipelines**: Set configuration in pipeline env
* **Quick testing**: Temporary configuration without files
* **System-wide defaults**: Set in shell profile

**Priority Order** (highest to lowest):

1. Command line flags
2. **Environment variables**
3. Configuration file
4. Default values

### Gonzo-Specific Variables

#### Input Configuration

**`GONZO_FILES`**

**Type**: String (comma-separated paths)\
**Default**: `""` (uses stdin)\
**Description**: Log files to read

```bash
# Single file
export GONZO_FILES="/var/log/app.log"

# Multiple files
export GONZO_FILES="/var/log/app.log,/var/log/error.log"

# Glob pattern (quote to prevent shell expansion)
export GONZO_FILES="/var/log/*.log"
```

**Example**:

```bash
export GONZO_SKIN="dracula"
```

**Built-in skins**:

* Dark: `default`, `controltheory-dark`, `dracula`, `gruvbox`, `monokai`, `nord`, `solarized-dark`
* Light: `controltheory-light`, `github-light`, `solarized-light`, `vs-code-light`, `spring`

#### Advanced Settings

**`GONZO_TEST_MODE`**

**Type**: Boolean (`true` or `false`)\
**Default**: `false`\
**Description**: Run without TTY (for testing)

```bash
export GONZO_TEST_MODE="true"
```

**Note**: For automated testing only, not for normal use.

### AI Provider Variables

These configure AI provider connections:

#### OpenAI API

**`OPENAI_API_KEY`**

**Type**: String (API key)\
**Required for**: OpenAI API access\
**Description**: Your OpenAI API key

```bash
export OPENAI_API_KEY="sk-your-actual-api-key-here"
```

**Get your key**: <https://platform.openai.com/api-keys>

**`OPENAI_API_BASE`**

**Type**: String (URL)\
**Default**: `https://api.openai.com/v1`\
**Description**: API endpoint (for custom providers)

```bash
# For OpenAI (default, can omit)
export OPENAI_API_BASE="https://api.openai.com/v1"

# For LM Studio (MUST include /v1)
export OPENAI_API_BASE="http://localhost:1234/v1"

# For Ollama (NO /v1 suffix)
export OPENAI_API_BASE="http://localhost:11434"

# For custom OpenAI-compatible API
export OPENAI_API_BASE="https://your-api.com/v1"
```

**Important Notes**:

* LM Studio: **MUST** include `/v1` suffix
* Ollama: **MUST NOT** include `/v1` suffix
* Most others: Include `/v1` suffix

#### OpenAI Configuration

**`OPENAI_ORGANIZATION`**

**Type**: String (organization ID)\
**Optional**: For multi-org accounts\
**Description**: OpenAI organization ID

```bash
export OPENAI_ORGANIZATION="org-your-org-id"
```

### System Variables

These system-wide variables affect Gonzo:

#### Terminal Configuration

**`TERM`**

**Type**: String\
**Default**: Set by terminal\
**Description**: Terminal type

```bash
export TERM="xterm-256color"
```

**Recommended values**:

* `xterm-256color` - 256 color support
* `screen-256color` - For tmux/screen
* `alacritty` - For Alacritty terminal

**`LANG` / `LC_ALL`**

**Type**: String (locale)\
**Default**: System locale\
**Description**: Character encoding

```bash
export LANG="en_US.UTF-8"
export LC_ALL="en_US.UTF-8"
```

**Note**: UTF-8 recommended for proper display.

#### Display Control

**`NO_COLOR`**

**Type**: Boolean (any value)\
**Default**: Not set\
**Description**: Disable color output

```bash
# Disable colors
export NO_COLOR=1

# Re-enable colors
unset NO_COLOR
```

**Note**: Setting to any value disables colors.

### Complete Configuration Examples

#### Basic Development Setup

```bash
# ~/.bashrc or ~/.zshrc
export GONZO_FILES="/var/log/app.log"
export GONZO_FOLLOW="true"
export GONZO_SKIN="dracula"
export OPENAI_API_KEY="sk-your-key-here"
```

#### Production Monitoring

```bash
# Production server configuration
export GONZO_FILES="/var/log/production/*.log"
export GONZO_FOLLOW="true"
export GONZO_UPDATE_INTERVAL="2s"
export GONZO_LOG_BUFFER="5000"
export GONZO_MEMORY_SIZE="20000"
export GONZO_SKIN="default"
export OPENAI_API_KEY="sk-prod-key"
```

#### OTLP Receiver

```bash
# OTLP log receiver setup
export GONZO_OTLP_ENABLED="true"
export GONZO_OTLP_GRPC_PORT="4317"
export GONZO_OTLP_HTTP_PORT="4318"
export GONZO_UPDATE_INTERVAL="1s"
export GONZO_LOG_BUFFER="2000"
```

#### Local AI with Ollama

```bash
# Using Ollama for AI features
export OPENAI_API_KEY="ollama"
export OPENAI_API_BASE="http://localhost:11434"
export GONZO_AI_MODEL="llama3"
export GONZO_FILES="/var/log/app.log"
export GONZO_FOLLOW="true"
```

#### Local AI with LM Studio

```bash
# Using LM Studio for AI features
export OPENAI_API_KEY="local-key"
export OPENAI_API_BASE="http://localhost:1234/v1"  # Note: /v1 required
export GONZO_AI_MODEL=""  # Auto-select
export GONZO_FILES="/var/log/app.log"
```

### Docker/Container Usage

#### Docker Compose

```yaml
# docker-compose.yml
services:
  gonzo:
    image: gonzo:latest
    environment:
      - GONZO_OTLP_ENABLED=true
      - GONZO_OTLP_GRPC_PORT=4317
      - GONZO_OTLP_HTTP_PORT=4318
      - GONZO_LOG_BUFFER=2000
      - GONZO_UPDATE_INTERVAL=2s
      - OPENAI_API_KEY=${OPENAI_API_KEY}
    ports:
      - "4317:4317"
      - "4318:4318"
```

#### Docker Run

```bash
docker run -e GONZO_OTLP_ENABLED=true \
           -e GONZO_OTLP_GRPC_PORT=4317 \
           -e GONZO_OTLP_HTTP_PORT=4318 \
           -e OPENAI_API_KEY="${OPENAI_API_KEY}" \
           -p 4317:4317 \
           -p 4318:4318 \
           gonzo:latest
```

#### Kubernetes

```yaml
# kubernetes-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: gonzo
spec:
  template:
    spec:
      containers:
      - name: gonzo
        image: gonzo:latest
        env:
        - name: GONZO_OTLP_ENABLED
          value: "true"
        - name: GONZO_OTLP_GRPC_PORT
          value: "4317"
        - name: GONZO_OTLP_HTTP_PORT
          value: "4318"
        - name: GONZO_LOG_BUFFER
          value: "2000"
        - name: OPENAI_API_KEY
          valueFrom:
            secretKeyRef:
              name: gonzo-secrets
              key: openai-api-key
        ports:
        - containerPort: 4317
        - containerPort: 4318
```

### Shell Profile Setup

#### Bash (\~/.bashrc)

```bash
# Gonzo Configuration
export GONZO_FILES="/var/log/app.log"
export GONZO_FOLLOW="true"
export GONZO_SKIN="dracula"
export GONZO_UPDATE_INTERVAL="2s"

# OpenAI Configuration
export OPENAI_API_KEY="sk-your-key-here"

# Optional: Add completion
if [ -f ~/.gonzo-completion.bash ]; then
  source ~/.gonzo-completion.bash
fi
```

#### Zsh (\~/.zshrc)

```zsh
# Gonzo Configuration
export GONZO_FILES="/var/log/app.log"
export GONZO_FOLLOW="true"
export GONZO_SKIN="nord"
export GONZO_UPDATE_INTERVAL="2s"

# OpenAI Configuration
export OPENAI_API_KEY="sk-your-key-here"

# Optional: Add completion
if [ -f ~/.gonzo-completion.zsh ]; then
  source ~/.gonzo-completion.zsh
fi
```

#### Fish (\~/.config/fish/config.fish)

```fish
# Gonzo Configuration
set -x GONZO_FILES "/var/log/app.log"
set -x GONZO_FOLLOW "true"
set -x GONZO_SKIN "monokai"
set -x GONZO_UPDATE_INTERVAL "2s"

# OpenAI Configuration
set -x OPENAI_API_KEY "sk-your-key-here"
```

### Debugging Environment Variables

#### View All Gonzo Variables

```bash
# Show all GONZO_* variables
env | grep GONZO

# Show all OpenAI variables
env | grep OPENAI

# Show all relevant variables
env | grep -E '(GONZO|OPENAI|TERM|LANG)'
```

#### Test Configuration

```bash
# Print configuration without starting Gonzo
gonzo --help

# Or check specific values
echo "Files: $GONZO_FILES"
echo "Follow: $GONZO_FOLLOW"
echo "Interval: $GONZO_UPDATE_INTERVAL"
echo "API Key: ${OPENAI_API_KEY:0:10}..."  # Show only first 10 chars
```

#### Clear All Settings

```bash
# Unset all Gonzo variables
unset GONZO_FILES
unset GONZO_FOLLOW
unset GONZO_UPDATE_INTERVAL
unset GONZO_LOG_BUFFER
unset GONZO_MEMORY_SIZE
unset GONZO_AI_MODEL
unset GONZO_OTLP_ENABLED
unset GONZO_OTLP_GRPC_PORT
unset GONZO_OTLP_HTTP_PORT
unset GONZO_SKIN

# Unset OpenAI variables
unset OPENAI_API_KEY
unset OPENAI_API_BASE
```

### Precedence Examples

Understanding how different configuration methods interact:

#### Example 1: Command Line Overrides Env Var

```bash
export GONZO_UPDATE_INTERVAL="5s"
gonzo --update-interval=1s  # Uses 1s, not 5s
```

#### Example 2: Env Var Overrides Config File

```yaml
# config.yml has: update-interval: 10s
```

```bash
export GONZO_UPDATE_INTERVAL="2s"
gonzo --config=config.yml  # Uses 2s, not 10s
```

#### Example 3: Full Precedence Chain

```yaml
# config.yml
update-interval: 10s
```

```bash
export GONZO_UPDATE_INTERVAL="5s"
gonzo --config=config.yml --update-interval=1s
# Result: Uses 1s (flag > env > config)
```

### Security Considerations

#### API Keys

**Never commit API keys**:

```bash
# ❌ BAD - Don't commit to version control
export OPENAI_API_KEY="sk-actual-key"

# ✅ GOOD - Use secrets management
export OPENAI_API_KEY="${OPENAI_KEY_FROM_VAULT}"

# ✅ GOOD - Read from secure file
export OPENAI_API_KEY=$(cat ~/.secrets/openai_key)
```

**Use environment-specific keys**:

```bash
# Development
export OPENAI_API_KEY="sk-dev-key"

# Production
export OPENAI_API_KEY="sk-prod-key"
```

#### File Permissions

Protect your shell profile:

```bash
chmod 600 ~/.bashrc
chmod 600 ~/.zshrc
```

#### Kubernetes Secrets

Store sensitive values in secrets:

```yaml
apiVersion: v1
kind: Secret
metadata:
  name: gonzo-secrets
type: Opaque
stringData:
  openai-api-key: "sk-your-key-here"
```

### Troubleshooting

#### Variable Not Applied

**Check if set**:

```bash
echo $GONZO_FILES
# If empty, not set
```

**Check for typos**:

```bash
# Wrong
export GONZO_FILE="/var/log/app.log"  # Missing 'S'

# Correct
export GONZO_FILES="/var/log/app.log"
```

**Check for overrides**:

```bash
# Command line flag overrides env var
gonzo -f other.log  # Ignores GONZO_FILES
```

#### AI Not Working

**Check API key**:

```bash
echo $OPENAI_API_KEY
# Should show your key (sk-...)
```

**Check API base**:

```bash
echo $OPENAI_API_BASE
# Should be correct for your provider
```

**Test connectivity**:

```bash
# For OpenAI
curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY"

# For LM Studio
curl http://localhost:1234/v1/models

# For Ollama
curl http://localhost:11434/api/tags
```

#### OTLP Receiver Not Starting

**Check if enabled**:

```bash
echo $GONZO_OTLP_ENABLED
# Should be "true"
```

**Check port conflicts**:

```bash
# Check if ports are free
lsof -i :4317
lsof -i :4318
```

### Best Practices

1. **Use shell profiles**: Set persistent defaults in `~/.bashrc` or `~/.zshrc`
2. **Separate environments**: Use different values for dev/prod
3. **Secure API keys**: Never commit keys to version control
4. **Document setup**: Comment your environment configuration
5. **Test changes**: Verify variables are applied correctly
6. **Use defaults**: Only override what you need to change

### Related Documentation

* **Configuration Schema** - Configuration file reference
* **CLI Reference** - Command line options
* **AI Integration** - AI provider setup

{% hint style="info" %}
**Tip**: Use `env | grep GONZO` to quickly see all your current Gonzo environment settings.
{% endhint %}

{% hint style="warning" %}
**Security**: Never expose API keys in logs, screenshots, or public repositories. Use environment variables or secrets management.
{% endhint %}

\_FILES="/var/log/nginx/access.log,/var/log/nginx/error.log" gonzo \`\`\`

**`GONZO_FOLLOW`**

**Type**: Boolean (`true` or `false`)\
**Default**: `false`\
**Description**: Follow log files in real-time

```bash
export GONZO_FOLLOW="true"
```

**Example**:

```bash
export GONZO_FOLLOW="true"
export GONZO_FILES="/var/log/app.log"
gonzo
```

#### Performance Settings

**`GONZO_UPDATE_INTERVAL`**

**Type**: Duration string\
**Default**: `"1s"`\
**Valid values**: Go duration format (e.g., `500ms`, `2s`, `5s`)\
**Description**: Dashboard update frequency

```bash
export GONZO_UPDATE_INTERVAL="2s"
```

**Common values**:

* `"500ms"` - Very responsive
* `"1s"` - Default, good balance
* `"2s"` - Reduced CPU usage
* `"5s"` - Low resource usage

**`GONZO_LOG_BUFFER`**

**Type**: Integer\
**Default**: `1000`\
**Valid range**: `1` to `100000`\
**Description**: Maximum log entries in buffer

```bash
export GONZO_LOG_BUFFER="2000"
```

**Guidelines**:

* **Low volume** (`<100 logs/sec`): 500-1000
* **Medium volume** (`100-1000 logs/sec`): 1000-5000
* **High volume** (`>1000 logs/sec`): 5000-10000

**`GONZO_MEMORY_SIZE`**

**Type**: Integer\
**Default**: `10000`\
**Valid range**: `100` to `1000000`\
**Description**: Maximum words tracked for frequency analysis

```bash
export GONZO_MEMORY_SIZE="15000"
```

**Guidelines**:

* **Minimal**: 5000
* **Standard**: 10000 (default)
* **Extended**: 15000-20000
* **Maximum**: 50000+

#### AI Configuration

**`GONZO_AI_MODEL`**

**Type**: String\
**Default**: `""` (auto-select)\
**Description**: AI model for log analysis

```bash
# Auto-select best available (recommended)
export GONZO_AI_MODEL=""

# OpenAI models
export GONZO_AI_MODEL="gpt-4"
export GONZO_AI_MODEL="gpt-3.5-turbo"

# Ollama models
export GONZO_AI_MODEL="llama3"
export GONZO_AI_MODEL="mistral"

# LM Studio models
export GONZO_AI_MODEL="openai/gpt-oss-120b"
```

#### OTLP Receiver

**`GONZO_OTLP_ENABLED`**

**Type**: Boolean (`true` or `false`)\
**Default**: `false`\
**Description**: Enable OTLP log receiver

```bash
export GONZO_OTLP_ENABLED="true"
```

**`GONZO_OTLP_GRPC_PORT`**

**Type**: Integer\
**Default**: `4317`\
**Valid range**: `1024` to `65535`\
**Description**: gRPC receiver port

```bash
export GONZO_OTLP_GRPC_PORT="4317"
```

**`GONZO_OTLP_HTTP_PORT`**

**Type**: Integer\
**Default**: `4318`\
**Valid range**: `1024` to `65535`\
**Description**: HTTP receiver port

```bash
export GONZO_OTLP_HTTP_PORT="4318"
```

#### Display Settings

**`GONZO_SKIN`**

**Type**: String\
**Default**: `"default"`\
**Valid values**: Any installed skin name\
**Description**: Color scheme/theme

```bash
export GONZO
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.controltheory.com/controltheory-documentation/gonzo-docs/reference/environment-variables.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.