Skip to content

Configuration

Jump to bottom
andershsueh edited this page Feb 10, 2026 · 2 revisions

Configuration Guide

📖 Languages: English only | 中文翻译征集中 | 日本語翻訳募集中

Complete guide to configuring ALICE.

Configuration File Location

~/.alice/settings.jsonc

Platform-specific paths:

  • Windows: C:\Users\<username>\.alice\settings.jsonc
  • macOS: /Users/<username>/.alice/settings.jsonc
  • Linux: /home/<username>/.alice/settings.jsonc

Initial Setup

On first run, ALICE creates the configuration directory and file automatically with default values.

Configuration Format

ALICE uses JSONC (JSON with Comments) format:

{
  // Workspace settings
  "workspace": ".",
  
  // LLM configuration
  "llm": {
    "model": "auto",
    "baseURL": "http://localhost:1234/v1",
    "apiKey": "",
    "temperature": 0.7,
    "maxTokens": 2000
  },
  
  // Tool safety
  "dangerous_cmd": true
}

Configuration Options

Workspace Settings

workspace

Type: string
Default: "."
Description: Default working directory for ALICE

{
  "workspace": "."  // Current directory
}

Examples:

"workspace": "D:\\projects\\myproject"  // Windows
"workspace": "/home/user/projects"       // Linux/macOS
"workspace": "~/Documents/work"          // Home directory

LLM Configuration

llm.model

Type: string
Default: "auto"
Description: LLM model to use

{
  "llm": {
    "model": "auto"  // Let LM Studio choose
  }
}

Options:

  • "auto" - LM Studio picks best available model
  • "gpt-3.5-turbo" - OpenAI GPT-3.5
  • "gpt-4" - OpenAI GPT-4
  • "deepseek-coder" - DeepSeek Coder
  • Any model supported by your backend

See Model Configuration Guide →

llm.baseURL

Type: string
Default: "http://localhost:1234/v1"
Description: LLM API endpoint

{
  "llm": {
    "baseURL": "http://localhost:1234/v1"  // LM Studio default
  }
}

Common endpoints:

// LM Studio
"baseURL": "http://localhost:1234/v1"

// OpenAI
"baseURL": "https://api.openai.com/v1"

// Ollama
"baseURL": "http://localhost:11434/v1"

// Custom
"baseURL": "https://my-llm-server.com/v1"

llm.apiKey

Type: string
Default: ""
Description: API key for LLM service

{
  "llm": {
    "apiKey": "sk-your-api-key-here"
  }
}

⚠️ Security Recommendations:

  • Never commit API keys to Git
  • Use environment variables instead: $OPENAI_API_KEY
  • LM Studio doesn't require API key

See Environment Variables Guide →

llm.temperature

Type: number (0.0 - 2.0)
Default: 0.7
Description: Controls response randomness

{
  "llm": {
    "temperature": 0.7  // Balanced creativity
  }
}

Guidelines:

  • 0.0 - 0.3 - Focused, deterministic (code generation)
  • 0.4 - 0.8 - Balanced (general chat)
  • 0.9 - 2.0 - Creative, diverse (brainstorming)

llm.maxTokens

Type: number
Default: 2000
Description: Maximum tokens per response

{
  "llm": {
    "maxTokens": 2000  // About 1500 words
  }
}

Token guidelines:

  • 500 - Short answers
  • 1000 - Normal responses
  • 2000 - Detailed responses (default)
  • 4000+ - Very long responses (slower)

Tool Safety

dangerous_cmd

Type: boolean
Default: true (recommended)
Description: Require confirmation for dangerous commands

{
  "dangerous_cmd": true  // Ask before dangerous operations
}

Behavior:

  • true - Show confirmation dialog for dangerous commands (recommended)
  • false - Execute all commands without asking (⚠️ dangerous!)

Dangerous operations:

  • File deletion (rm -rf, del /s)
  • Disk formatting (format, mkfs)
  • System shutdown (shutdown, reboot)
  • Disk operations (dd if=)

Learn more about dangerous commands →

Configuration Examples

For OpenAI API

{
  "workspace": ".",
  "llm": {
    "model": "gpt-4",
    "baseURL": "https://api.openai.com/v1",
    "apiKey": "$OPENAI_API_KEY",  // Use environment variable
    "temperature": 0.7,
    "maxTokens": 2000
  },
  "dangerous_cmd": true
}

For LM Studio (Local)

{
  "workspace": ".",
  "llm": {
    "model": "auto",
    "baseURL": "http://localhost:1234/v1",
    "apiKey": "",  // Not needed
    "temperature": 0.7,
    "maxTokens": 2000
  },
  "dangerous_cmd": true
}

For Code Generation

{
  "workspace": "~/projects",
  "llm": {
    "model": "deepseek-coder",
    "baseURL": "http://localhost:1234/v1",
    "apiKey": "",
    "temperature": 0.2,  // More focused
    "maxTokens": 4000    // Longer code
  },
  "dangerous_cmd": true  // Still ask for confirmation
}

Power User (No Confirmations)

{
  "workspace": ".",
  "llm": {
    "model": "gpt-4",
    "baseURL": "https://api.openai.com/v1",
    "apiKey": "$OPENAI_API_KEY",
    "temperature": 0.7,
    "maxTokens": 2000
  },
  "dangerous_cmd": false  // ⚠️ No safety confirmations!
}

Advanced Configuration

Using Environment Variables

Instead of hardcoding API keys:

{
  "llm": {
    "apiKey": "$OPENAI_API_KEY"  // Reads from environment
  }
}

Set in your shell:

# Windows (PowerShell)
$env:OPENAI_API_KEY="sk-your-key"

# macOS/Linux (Bash)
export OPENAI_API_KEY="sk-your-key"

Full environment variables guide →

Multi-Model Setup

Switch between models:

{
  "llm": {
    "model": "gpt-4",  // Change this to switch models
    "baseURL": "https://api.openai.com/v1",
    "apiKey": "$OPENAI_API_KEY",
    "temperature": 0.7,
    "maxTokens": 2000
  }
}

Learn about multi-model setups →

Updating Configuration

Option 1: Edit Manually

Open the file in your editor:

# Windows
notepad %USERPROFILE%\.alice\settings.jsonc

# macOS
open ~/.alice/settings.jsonc

# Linux
nano ~/.alice/settings.jsonc

Changes take effect on next ALICE restart.

Option 2: Reset to Defaults

Delete the configuration file:

# Windows
del %USERPROFILE%\.alice\settings.jsonc

# macOS/Linux
rm ~/.alice/settings.jsonc

ALICE will recreate it with defaults on next run.

Configuration Validation

ALICE validates your configuration on startup.

Common Errors

Invalid JSON

❌ Error: Failed to parse settings.jsonc
   Syntax error at line 5

Solution: Check for missing commas, quotes, brackets

Invalid baseURL

❌ Error: Invalid baseURL
   Must start with http:// or https://

Solution: Use full URL with protocol

Invalid temperature

❌ Error: temperature must be between 0.0 and 2.0

Solution: Use value in valid range

Troubleshooting

Configuration Not Loading

Problem: Changes don't take effect

Solutions:

  • Restart ALICE
  • Check file location: ~/.alice/settings.jsonc
  • Verify JSON syntax (use JSON validator)

Can't Find Configuration File

Problem: File doesn't exist

Solutions:

  • Run ALICE once to auto-create
  • Create manually with defaults
  • Check user home directory

API Key Not Working

Problem: Authentication fails

Solutions:

  • Verify API key is correct
  • Check environment variable is set
  • Try hardcoding key (temporarily)
  • Ensure no extra spaces/quotes

More troubleshooting →

See Also

Clone this wiki locally