# Settings and Configuration

Voxcode can be configured through environment variables and runtime settings.

## Configuration Layers

1. **Environment variables**: best for secrets and CI runtime behavior
2. **Config files**: best for stable defaults and team conventions
3. **CLI flags**: best for one-off overrides

## Common Environment Variables

| Variable | Purpose |
| --- | --- |
| `VOXCODE_OFFLINE` | Disable network-dependent features where possible |
| `VOXCODE_SKIP_VERSION_CHECK` | Skip update/version check logic |
| `VOXCODE_TELEMETRY` | Toggle telemetry behavior |
| `VOXCODE_CONFIG_DIR` | Override default config directory |
| `VOXCODE_SHARE_VIEWER_URL` | Customize share viewer endpoint |
| `VOXCODE_TUI_DEBUG` | Enable TUI debug behavior |

Provider secrets (examples):

- `ANTHROPIC_API_KEY`
- `OPENAI_API_KEY`
- `GEMINI_API_KEY`
- `MISTRAL_API_KEY`

## JSON Config File

Config disimpan di `~/.config/voxcode/settings.json` (global) dan `.voxcode/settings.json` (project — override global).

### Permission System

```json
{
  "permission": {
    "bash": "ask",
    "edit": "allow",
    "write": "deny"
  }
}
```

Path-based wildcards untuk file-scoped rules:

```json
{
  "permission": {
    "edit": { "src/*": "allow", "*": "deny" }
  }
}
```

- `"allow"` — izinkan tanpa konfirmasi
- `"deny"` — blokir
- `"ask"` — tanya user (hanya di TUI; di headless mode = block)

Tool yang gak disebut default-nya `"allow"`.

### MCP Servers

Daftarkan MCP server untuk menambah tools ke agent:

```json
{
  "mcp": {
    "playwright": { "command": "npx", "args": ["@playwright/mcp"], "enabled": true }
  }
}
```

Tools teregister otomatis dengan prefix `serverName_toolName`.

## Recommended Setup Pattern

- Keep provider keys in shell env or secret manager
- Commit non-secret defaults in project config
- Override per session when needed

## Example: Shell Profile

```bash
export ANTHROPIC_API_KEY="your-key"
export VOXCODE_TELEMETRY="0"
```

## Example: Per-Command Override

```bash
VOXCODE_OFFLINE=1 vox -p "Analyze local files only"
```

## Troubleshooting

- config not applied: verify variable name and shell scope
- provider auth errors: verify key is exported in current shell
- inconsistent behavior: check for conflicting env vars and CLI flags
