Skip to main content
Strix automatically saves your environment variables to a configuration file at ~/.strix/cli-config.json. This allows you to configure Strix once and have your settings persist across runs.

​
Location

The default configuration file is located at: 
~/.strix/cli-config.json
You can override this location using the --config flag: 
strix --target ./app --config /path/to/custom-config.json

​
File Format

The configuration file uses JSON format and stores environment variables in an env object: 
{
  "env": {
    "STRIX_LLM": "openai/gpt-5",
    "LLM_API_KEY": "sk-...",
    "PERPLEXITY_API_KEY": "pplx-...",
    "STRIX_REASONING_EFFORT": "high",
    "STRIX_SANDBOX_EXECUTION_TIMEOUT": "120"
  }
}

​
How It Works

​
Automatic Saving

When you run Strix with environment variables set, they are automatically saved to the config file: 
# First run - set environment variables
export STRIX_LLM="openai/gpt-5"
export LLM_API_KEY="sk-..."
strix --target ./app

# Configuration is now saved to ~/.strix/cli-config.json
# Future runs don't need environment variables
strix --target ./app

​
Automatic Loading

On subsequent runs, Strix automatically loads saved configuration:
  1. Strix reads ~/.strix/cli-config.json
  2. Applies saved variables if they’re not already set in the environment
  3. Uses environment variables if they’re set (they take precedence)

​
Configuration Priority

Strix uses this priority order for configuration:
  1. Environment variables - Highest priority
  2. Custom config file (via --config) - Overrides default config
  3. Default config file (~/.strix/cli-config.json) - Lowest priority

​
Managing Configuration

​
View Current Configuration

To see your saved configuration, read the file: 
cat ~/.strix/cli-config.json
Or use jq for pretty printing: 
jq . ~/.strix/cli-config.json

​
Update Configuration

You can update configuration in two ways:

​
Method 1: Set Environment Variables

Set new environment variables and run Strix. They will be automatically saved: 
export STRIX_LLM="anthropic/claude-sonnet-4-6"
strix --target ./app

​
Method 2: Edit Config File Directly

Edit ~/.strix/cli-config.json manually: 
nano ~/.strix/cli-config.json

{
  "env": {
    "STRIX_LLM": "anthropic/claude-sonnet-4-6",
    "LLM_API_KEY": "sk-ant-...",
    "STRIX_REASONING_EFFORT": "medium"
  }
}
Make sure the config file has correct JSON syntax. Invalid JSON will cause the configuration to be ignored.

​
Clear Configuration

To remove a specific variable, set it to an empty string: 
export STRIX_LLM=""
strix --target ./app
This removes STRIX_LLM from the saved configuration. To clear all configuration, delete the file: 
rm ~/.strix/cli-config.json

​
Validate Configuration

Strix validates the configuration file on startup. If the file is corrupted or invalid, Strix will:
  1. Log a warning
  2. Ignore the invalid configuration
  3. Use environment variables or defaults

​
Security Considerations

​
File Permissions

The config file is automatically created with restricted permissions (0600 on Unix-like systems): 
-rw-------  1 user  user  256 Mar 01 12:00 cli-config.json
This ensures that only you can read the file, protecting your API keys.

​
Storing Secrets

While the config file is convenient, consider these alternatives for sensitive data:
  1. Environment variables - Don’t persist to disk
  2. Secret management tools - Use tools like 1Password, AWS Secrets Manager
  3. CI/CD secrets - Use GitHub Secrets, GitLab CI/CD variables

​
Avoid Committing Config Files

Never commit your config file to version control: 
# Add to .gitignore
echo ".strix/" >> .gitignore

​
Custom Config Files

​
Using Custom Locations

You can use a custom config file location with the --config flag: 
strix --target ./app --config /path/to/project-config.json
This is useful for:
  • Project-specific configurations
  • Team-shared configurations (without secrets)
  • CI/CD environments

​
Template Example

Create a team config template without secrets: 
{
  "env": {
    "STRIX_LLM": "openai/gpt-5",
    "STRIX_REASONING_EFFORT": "medium",
    "STRIX_SANDBOX_EXECUTION_TIMEOUT": "180",
    "STRIX_DISABLE_BROWSER": "false"
  }
}
Team members can copy this and add their API keys: 
cp team-config.json ~/.strix/cli-config.json
# Edit and add LLM_API_KEY
nano ~/.strix/cli-config.json

​
Tracked Variables

Strix automatically tracks and saves these environment variables:

​
LLM Configuration

  • STRIX_LLM
  • LLM_API_KEY
  • LLM_API_BASE
  • OPENAI_API_BASE
  • LITELLM_BASE_URL
  • OLLAMA_API_BASE
  • STRIX_REASONING_EFFORT
  • STRIX_LLM_MAX_RETRIES
  • STRIX_MEMORY_COMPRESSOR_TIMEOUT
  • LLM_TIMEOUT

​
Tool Configuration

  • PERPLEXITY_API_KEY
  • STRIX_DISABLE_BROWSER

​
Runtime Configuration

  • STRIX_IMAGE
  • STRIX_RUNTIME_BACKEND
  • STRIX_SANDBOX_EXECUTION_TIMEOUT
  • STRIX_SANDBOX_CONNECT_TIMEOUT

​
Telemetry

  • STRIX_TELEMETRY
DOCKER_HOST is not tracked in the config file. It should be set as an environment variable if needed.

​
Special Behaviors

​
LLM Config Re-validation

LLM-related variables (STRIX_LLM, LLM_API_KEY, etc.) are re-validated on each run:
  • If you change these variables in your environment, Strix uses the new values
  • The saved configuration is updated with the new values
  • This ensures your LLM config is always up to date

​
Custom Config Override

When using --config, Strix:
  1. Does not automatically save changes to the custom config file
  2. Uses the custom config file as read-only
  3. Still respects environment variables (they take precedence)
This prevents accidental modification of team or project configs.

​
Troubleshooting

​
Config Not Loading

If your saved config isn’t being used:
  1. Check file permissions: ls -la ~/.strix/cli-config.json
  2. Validate JSON syntax: jq . ~/.strix/cli-config.json
  3. Ensure environment variables aren’t overriding saved values
  4. Check for typos in variable names

​
Config File Corruption

If the config file is corrupted: 
# Backup the file
cp ~/.strix/cli-config.json ~/.strix/cli-config.json.bak

# Delete and recreate
rm ~/.strix/cli-config.json
export STRIX_LLM="openai/gpt-5"
export LLM_API_KEY="sk-..."
strix --target ./app

​
Permission Denied

If you see permission errors: 
# Fix permissions
chmod 600 ~/.strix/cli-config.json

# Fix ownership (if needed)
chown $USER ~/.strix/cli-config.json

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us