Configuration

Where config lives

By default, Paseo uses ~/.paseo as its home directory. The configuration file is:

You can change the home directory by setting PASEO_HOME or passing --home to paseo daemon start.

Precedence

Paseo merges configuration in this order:

1. Defaults
2. config.json
3. Environment variables
4. CLI flags

Lists append across sources (for example, allowedHosts andcors.allowedOrigins).

Example

Minimal example that configures listening address, host allowlist, provider keys, and MCP:

{
  "$schema": "https://paseo.sh/schemas/paseo.config.v1.json",
  "version": 1,
  "providers": {
    "openai": { "apiKey": "..." }
  },
  "daemon": {
    "listen": "127.0.0.1:6767",
    "allowedHosts": ["localhost", ".localhost"],
    "mcp": { "enabled": true }
  }
}

Agent provider runtime settings

Use agents.providers to customize how Paseo launches agent provider CLIs. This works for claude, codex, and opencode.

command.mode can be default, append, or replace. Use env to inject provider-specific environment variables.

Enable Claude Code Chrome MCP

{
  "agents": {
    "providers": {
      "claude": {
        "command": {
          "mode": "append",
          "args": ["--chrome"]
        }
      }
    }
  }
}

Point Claude to Anthropic-compatible endpoints (z.ai example)

{
  "agents": {
    "providers": {
      "claude": {
        "env": {
          "ANTHROPIC_BASE_URL": "https://api.z.ai/api/anthropic",
          "ANTHROPIC_AUTH_TOKEN": "auth token",
          "ANTHROPIC_API_KEY": ""
        }
      }
    }
  }
}

Run Claude through Docker

Create a wrapper script that runs Claude in Docker, then tell Paseo to replace the Claude launch command with that script.

{
  "agents": {
    "providers": {
      "claude": {
        "command": {
          "mode": "replace",
          "argv": ["/Users/you/bin/claude-docker"]
        }
      }
    }
  }
}

#!/usr/bin/env bash
set -euo pipefail
docker run --rm -i \
  -v "$PWD":"$PWD" \
  -w "$PWD" \
  -v "$HOME/.claude":"$HOME/.claude" \
  ghcr.io/anthropics/claude-code:latest \
  claude "$@"

Voice

Voice is configured through features.dictation and features.voiceMode, with provider credentials under providers.

For voice philosophy, architecture, and complete local/OpenAI setup examples, see Voice docs.

Logging

Daemon logging uses separate console and file sinks by default:

• Console: info and above
• File ($PASEO_HOME/daemon.log): trace and above
• File rotation: 10m max file size, 2 retained files total (active + 1 rotated)

{
  "log": {
    "console": {
      "level": "info",
      "format": "pretty"
    },
    "file": {
      "level": "trace",
      "path": "daemon.log",
      "rotate": {
        "maxSize": "10m",
        "maxFiles": 2
      }
    }
  }
}

Legacy fields log.level and log.format are still supported and map to the new destination settings.

Common env vars

• PASEO_HOME — set Paseo home directory
• PASEO_LISTEN — override daemon.listen
• PASEO_ALLOWED_HOSTS — override/extend daemon.allowedHosts
• PASEO_LOG_CONSOLE_LEVEL — override log.console.level
• PASEO_LOG_FILE_LEVEL — override log.file.level
• PASEO_LOG_FILE_PATH — override log.file.path
• PASEO_LOG_FILE_ROTATE_SIZE — override log.file.rotate.maxSize
• PASEO_LOG_FILE_ROTATE_COUNT — override log.file.rotate.maxFiles
• PASEO_LOG, PASEO_LOG_FORMAT — legacy log overrides (still supported)
• OPENAI_API_KEY — override OpenAI provider key
• PASEO_VOICE_LLM_PROVIDER — override voice LLM provider (claude, codex, opencode)
• PASEO_DICTATION_STT_PROVIDER, PASEO_VOICE_STT_PROVIDER, PASEO_VOICE_TTS_PROVIDER — override voice provider selection (local or openai)
• PASEO_LOCAL_MODELS_DIR — control local model directory
• PASEO_DICTATION_LOCAL_STT_MODEL — override local dictation STT model
• PASEO_VOICE_LOCAL_STT_MODEL, PASEO_VOICE_LOCAL_TTS_MODEL — override local voice STT/TTS models
• PASEO_VOICE_LOCAL_TTS_SPEAKER_ID, PASEO_VOICE_LOCAL_TTS_SPEED — optional local voice TTS tuning

Schema

For editor autocomplete/validation, set $schema to: