308 lines
12 KiB
TypeScript
308 lines
12 KiB
TypeScript
import { createFileRoute } from "@tanstack/react-router";
|
|
import { pageMeta } from "~/meta";
|
|
|
|
export const Route = createFileRoute("/docs/configuration")({
|
|
head: () => ({
|
|
meta: pageMeta(
|
|
"Configuration - Paseo Docs",
|
|
"Configure Paseo via config.json, environment variables, and CLI overrides.",
|
|
),
|
|
}),
|
|
component: Configuration,
|
|
});
|
|
|
|
function Configuration() {
|
|
return (
|
|
<div className="space-y-8">
|
|
<div>
|
|
<h1 className="text-3xl font-medium font-title mb-4">Configuration</h1>
|
|
<p className="text-white/60 leading-relaxed">
|
|
Paseo loads configuration from a single JSON file in your Paseo home directory, with
|
|
optional environment variable and CLI overrides.
|
|
</p>
|
|
</div>
|
|
|
|
<section className="space-y-4">
|
|
<h2 className="text-xl font-medium">Where config lives</h2>
|
|
<p className="text-white/60 leading-relaxed">
|
|
By default, Paseo uses <code className="font-mono">~/.paseo</code> as its home directory.
|
|
The configuration file is:
|
|
</p>
|
|
<div className="bg-card border border-border rounded-lg p-4 font-mono text-sm">
|
|
<span className="text-muted-foreground select-none">$ </span>
|
|
<span>~/.paseo/config.json</span>
|
|
</div>
|
|
<p className="text-white/60 leading-relaxed">
|
|
You can change the home directory by setting <code className="font-mono">PASEO_HOME</code>{" "}
|
|
or passing <code className="font-mono">--home</code> to{" "}
|
|
<code className="font-mono">paseo daemon start</code>.
|
|
</p>
|
|
</section>
|
|
|
|
<section className="space-y-4">
|
|
<h2 className="text-xl font-medium">Precedence</h2>
|
|
<p className="text-white/60 leading-relaxed">Paseo merges configuration in this order:</p>
|
|
<ol className="text-white/60 space-y-2 list-decimal list-inside">
|
|
<li>Defaults</li>
|
|
<li>
|
|
<code className="font-mono">config.json</code>
|
|
</li>
|
|
<li>Environment variables</li>
|
|
<li>CLI flags</li>
|
|
</ol>
|
|
<p className="text-white/60 leading-relaxed">
|
|
Lists append across sources (for example, <code className="font-mono">allowedHosts</code>{" "}
|
|
and
|
|
<code className="font-mono">cors.allowedOrigins</code>).
|
|
</p>
|
|
</section>
|
|
|
|
<section className="space-y-4">
|
|
<h2 className="text-xl font-medium">Example</h2>
|
|
<p className="text-white/60 leading-relaxed">
|
|
Minimal example that configures listening address, host allowlist, provider keys, and MCP:
|
|
</p>
|
|
<pre className="bg-card border border-border rounded-lg p-4 font-mono text-sm overflow-x-auto text-white/80">
|
|
{`{
|
|
"$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 }
|
|
}
|
|
}`}
|
|
</pre>
|
|
</section>
|
|
|
|
<section className="space-y-4">
|
|
<h2 className="text-xl font-medium">Agent provider runtime settings</h2>
|
|
<p className="text-white/60 leading-relaxed">
|
|
Use <code className="font-mono">agents.providers</code> to customize how Paseo launches
|
|
agent provider CLIs. This works for <code className="font-mono">claude</code>,{" "}
|
|
<code className="font-mono">codex</code>, and
|
|
<code className="font-mono"> opencode</code>.
|
|
</p>
|
|
<p className="text-white/60 leading-relaxed">
|
|
<code className="font-mono">command.mode</code> can be{" "}
|
|
<code className="font-mono">default</code>, <code className="font-mono">append</code>, or{" "}
|
|
<code className="font-mono">replace</code>. Use <code className="font-mono">env</code> to
|
|
inject provider-specific environment variables.
|
|
</p>
|
|
|
|
<h3 className="text-lg font-medium">Enable Claude Code Chrome MCP</h3>
|
|
<pre className="bg-card border border-border rounded-lg p-4 font-mono text-sm overflow-x-auto text-white/80">
|
|
{`{
|
|
"agents": {
|
|
"providers": {
|
|
"claude": {
|
|
"command": {
|
|
"mode": "append",
|
|
"args": ["--chrome"]
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}`}
|
|
</pre>
|
|
|
|
<h3 className="text-lg font-medium">
|
|
Point Claude to Anthropic-compatible endpoints (z.ai example)
|
|
</h3>
|
|
<pre className="bg-card border border-border rounded-lg p-4 font-mono text-sm overflow-x-auto text-white/80">
|
|
{`{
|
|
"agents": {
|
|
"providers": {
|
|
"claude": {
|
|
"env": {
|
|
"ANTHROPIC_BASE_URL": "https://api.z.ai/api/anthropic",
|
|
"ANTHROPIC_AUTH_TOKEN": "auth token",
|
|
"ANTHROPIC_API_KEY": ""
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}`}
|
|
</pre>
|
|
|
|
<h3 className="text-lg font-medium">Run Claude through Docker</h3>
|
|
<p className="text-white/60 leading-relaxed">
|
|
Create a wrapper script that runs Claude in Docker, then tell Paseo to replace the Claude
|
|
launch command with that script.
|
|
</p>
|
|
<pre className="bg-card border border-border rounded-lg p-4 font-mono text-sm overflow-x-auto text-white/80">
|
|
{`{
|
|
"agents": {
|
|
"providers": {
|
|
"claude": {
|
|
"command": {
|
|
"mode": "replace",
|
|
"argv": ["/Users/you/bin/claude-docker"]
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}`}
|
|
</pre>
|
|
<pre className="bg-card border border-border rounded-lg p-4 font-mono text-sm overflow-x-auto text-white/80">
|
|
{`#!/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 "$@"`}
|
|
</pre>
|
|
</section>
|
|
|
|
<section className="space-y-4">
|
|
<h2 className="text-xl font-medium">Voice</h2>
|
|
<p className="text-white/60 leading-relaxed">
|
|
Voice is configured through <code className="font-mono">features.dictation</code> and{" "}
|
|
<code className="font-mono">features.voiceMode</code>, with provider credentials under{" "}
|
|
<code className="font-mono">providers</code>.
|
|
</p>
|
|
<p className="text-white/60 leading-relaxed">
|
|
For voice philosophy, architecture, and complete local/OpenAI setup examples, see{" "}
|
|
<a href="/docs/voice" className="underline hover:text-white/80">
|
|
Voice docs
|
|
</a>
|
|
.
|
|
</p>
|
|
</section>
|
|
|
|
<section className="space-y-4">
|
|
<h2 className="text-xl font-medium">Logging</h2>
|
|
<p className="text-white/60 leading-relaxed">
|
|
Daemon logging uses separate console and file sinks by default:
|
|
</p>
|
|
<ul className="text-white/60 space-y-2 list-disc list-inside">
|
|
<li>
|
|
Console: <code className="font-mono">info</code> and above
|
|
</li>
|
|
<li>
|
|
File (<code className="font-mono">$PASEO_HOME/daemon.log</code>):{" "}
|
|
<code className="font-mono">trace</code> and above
|
|
</li>
|
|
<li>
|
|
File rotation: <code className="font-mono">10m</code> max file size,{" "}
|
|
<code className="font-mono">2</code> retained files total (active + 1 rotated)
|
|
</li>
|
|
</ul>
|
|
<pre className="bg-card border border-border rounded-lg p-4 font-mono text-sm overflow-x-auto text-white/80">
|
|
{`{
|
|
"log": {
|
|
"console": {
|
|
"level": "info",
|
|
"format": "pretty"
|
|
},
|
|
"file": {
|
|
"level": "trace",
|
|
"path": "daemon.log",
|
|
"rotate": {
|
|
"maxSize": "10m",
|
|
"maxFiles": 2
|
|
}
|
|
}
|
|
}
|
|
}`}
|
|
</pre>
|
|
<p className="text-white/60 leading-relaxed">
|
|
Legacy fields <code className="font-mono">log.level</code> and{" "}
|
|
<code className="font-mono">log.format</code> are still supported and map to the new
|
|
destination settings.
|
|
</p>
|
|
</section>
|
|
|
|
<section className="space-y-4">
|
|
<h2 className="text-xl font-medium">Common env vars</h2>
|
|
<ul className="text-white/60 space-y-2 list-disc list-inside">
|
|
<li>
|
|
<code className="font-mono">PASEO_HOME</code> — set Paseo home directory
|
|
</li>
|
|
<li>
|
|
<code className="font-mono">PASEO_LISTEN</code> — override{" "}
|
|
<code className="font-mono">daemon.listen</code>
|
|
</li>
|
|
<li>
|
|
<code className="font-mono">PASEO_ALLOWED_HOSTS</code> — override/extend{" "}
|
|
<code className="font-mono">daemon.allowedHosts</code>
|
|
</li>
|
|
<li>
|
|
<code className="font-mono">PASEO_LOG_CONSOLE_LEVEL</code> — override{" "}
|
|
<code className="font-mono">log.console.level</code>
|
|
</li>
|
|
<li>
|
|
<code className="font-mono">PASEO_LOG_FILE_LEVEL</code> — override{" "}
|
|
<code className="font-mono">log.file.level</code>
|
|
</li>
|
|
<li>
|
|
<code className="font-mono">PASEO_LOG_FILE_PATH</code> — override{" "}
|
|
<code className="font-mono">log.file.path</code>
|
|
</li>
|
|
<li>
|
|
<code className="font-mono">PASEO_LOG_FILE_ROTATE_SIZE</code> — override{" "}
|
|
<code className="font-mono">log.file.rotate.maxSize</code>
|
|
</li>
|
|
<li>
|
|
<code className="font-mono">PASEO_LOG_FILE_ROTATE_COUNT</code> — override{" "}
|
|
<code className="font-mono">log.file.rotate.maxFiles</code>
|
|
</li>
|
|
<li>
|
|
<code className="font-mono">PASEO_LOG</code>,{" "}
|
|
<code className="font-mono">PASEO_LOG_FORMAT</code> — legacy log overrides (still
|
|
supported)
|
|
</li>
|
|
<li>
|
|
<code className="font-mono">OPENAI_API_KEY</code> — override OpenAI provider key
|
|
</li>
|
|
<li>
|
|
<code className="font-mono">PASEO_VOICE_LLM_PROVIDER</code> — override voice LLM
|
|
provider (<code className="font-mono">claude</code>,{" "}
|
|
<code className="font-mono">codex</code>, <code className="font-mono">opencode</code>)
|
|
</li>
|
|
<li>
|
|
<code className="font-mono">PASEO_DICTATION_STT_PROVIDER</code>,{" "}
|
|
<code className="font-mono">PASEO_VOICE_STT_PROVIDER</code>,{" "}
|
|
<code className="font-mono">PASEO_VOICE_TTS_PROVIDER</code> — override voice provider
|
|
selection (<code className="font-mono">local</code> or{" "}
|
|
<code className="font-mono">openai</code>)
|
|
</li>
|
|
<li>
|
|
<code className="font-mono">PASEO_LOCAL_MODELS_DIR</code> — control local model
|
|
directory
|
|
</li>
|
|
<li>
|
|
<code className="font-mono">PASEO_DICTATION_LOCAL_STT_MODEL</code> — override local
|
|
dictation STT model
|
|
</li>
|
|
<li>
|
|
<code className="font-mono">PASEO_VOICE_LOCAL_STT_MODEL</code>,{" "}
|
|
<code className="font-mono">PASEO_VOICE_LOCAL_TTS_MODEL</code> — override local voice
|
|
STT/TTS models
|
|
</li>
|
|
<li>
|
|
<code className="font-mono">PASEO_VOICE_LOCAL_TTS_SPEAKER_ID</code>,{" "}
|
|
<code className="font-mono">PASEO_VOICE_LOCAL_TTS_SPEED</code> — optional local voice
|
|
TTS tuning
|
|
</li>
|
|
</ul>
|
|
</section>
|
|
|
|
<section className="space-y-4">
|
|
<h2 className="text-xl font-medium">Schema</h2>
|
|
<p className="text-white/60 leading-relaxed">
|
|
For editor autocomplete/validation, set <code className="font-mono">$schema</code> to:
|
|
</p>
|
|
<div className="bg-card border border-border rounded-lg p-4 font-mono text-sm">
|
|
<span>https://paseo.sh/schemas/paseo.config.v1.json</span>
|
|
</div>
|
|
</section>
|
|
</div>
|
|
);
|
|
}
|