Skip to content

configuration.md

Latest commit

 

History

History
141 lines (98 loc) · 7.69 KB

configuration.md

File metadata and controls

141 lines (98 loc) · 7.69 KB
Raw

English | 中文

Configuration Reference

Dr. Claw is configured through environment variables in a .env file at the project root. This guide documents every variable the application reads.

How .env Loading Works

  1. Backend — server/load-env.js reads .env line-by-line on startup and sets any key not already present in process.env. System environment variables always take precedence.
  2. Frontend — Vite loads .env automatically. Only variables prefixed with VITE_ are exposed to browser code.
  3. Precedence — System env > .env file values.

Quick start: cp .env.example .env gives you sensible defaults. See the Quickstart guide for a step-by-step walkthrough.

Configuration Reference

Server

Variable Required Default Description
PORT No 3001 Express API + WebSocket server port.
VITE_PORT No 5173 Vite dev server port (development only).
CLAUDE_CLI_PATH No claude Absolute or relative path to the Claude Code binary. Override if claude is not on your PATH.
CURSOR_CLI_PATH No Auto-detect (cursor-agent then agent) Override Cursor CLI command/binary. Useful when your environment only provides one alias.
GEMINI_CLI_PATH No gemini Override Gemini CLI command/binary. Useful when your shell resolves Gemini through a custom alias or path.
CODEX_CLI_PATH No codex Override Codex CLI command/binary. Useful when Codex is installed outside your default PATH.

Database

Variable Required Default Description
DATABASE_PATH No server/database/auth.db Absolute path to the SQLite database file. The directory is created automatically if it does not exist.

Authentication

These variables are security-sensitive. See the Security Checklist below.

Variable Required Default Description
JWT_SECRET Yes (production) claude-ui-dev-secret-change-in-production Secret used to sign and verify JWT tokens. Must be changed before exposing Dr. Claw outside localhost. Generate one with: node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
API_KEY No (none — validation skipped) When set, every HTTP request must include an X-Api-Key header with this value. Useful for restricting access in hosted setups.

Context Window

Variable Required Default Description
CONTEXT_WINDOW No 160000 Maximum token context window sent to the backend CLI process.
VITE_CONTEXT_WINDOW No 160000 Same value exposed to the frontend (must match CONTEXT_WINDOW).

Platform Mode

Platform mode is an advanced deployment option. Most users should leave these commented out.

Variable Required Default Description
VITE_IS_PLATFORM No false Set to true to enable Platform mode. In this mode JWT authentication is bypassed and the first database user is used for all requests.
WORKSPACES_ROOT No User home directory (os.homedir()) Root directory where Dr. Claw looks for and creates project workspaces. Only meaningful when VITE_IS_PLATFORM=true.

Integrations

Variable Required Default Description
OPENAI_API_KEY No (none) OpenAI API key for Codex integration. Required only if you use the Codex CLI backend.

Advanced

Variable Required Default Description
CLAUDE_TOOL_APPROVAL_TIMEOUT_MS No 55000 Timeout in milliseconds for Claude tool-approval prompts before auto-declining.

Model Discovery

Dr. Claw asks each harness which models it actually supports rather than relying only on the list compiled into the app, so a CLI that ships a new model shows up without waiting for a Dr. Claw release.

Provider Source Notes
Claude Agent SDK supportedModels() control request The menu the bundled Claude Code CLI serves (e.g. default, opus[1m], claude-fable-5-1[1m], sonnet), so it tracks the SDK version Dr. Claw ships. The CLI also accepts ids it does not list, so built-in entries are kept without a deprecated marker. No tokens are consumed and settings/hooks are not loaded during the probe.
Codex codex app-server → model/list JSON-RPC Same catalogue the Codex CLI's own picker reads. Honours CODEX_CLI_PATH.
OpenRouter GET https://openrouter.ai/api/v1/models Public endpoint, no key needed.
Cursor, Gemini, Nano Built-in list These CLIs expose no model-listing command today.
Local GPU Ollama /api/tags Existing behaviour, unchanged.

Discovery is strictly additive and never blocks the UI:

  • Results are cached for 10 minutes; a failed probe is re-tried after 1 minute so the picker recovers on its own once a CLI is installed or logged in.
  • Every probe has a 15-second hard timeout. If the harness is missing, old, logged out, or unresponsive, the built-in list is used instead.
  • Models present in the built-in list but no longer served by the harness are kept at the end of the picker and marked deprecated, so an existing saved model preference is never stranded. (Not for Claude: its CLI runs ids it does not advertise, so nothing is demoted there.)

API

Endpoint Description
GET /api/models/:provider Model list for a provider. source is discovered or static. Add ?refresh=1 to bypass the cache.
POST /api/models/:provider/refresh Drop the cache and re-probe — useful right after upgrading or logging into a CLI.
GET /api/models/providers Providers this build can probe.

OSS Mode vs Platform Mode

Dr. Claw supports two authentication paths:

OSS Mode (default) Platform Mode
Who uses it Individual developers running Dr. Claw locally Hosted / multi-tenant deployments
Auth flow Register/login with username + password; JWT issued per session JWT auth bypassed; first DB user auto-selected
Enable Default — no extra config needed Set VITE_IS_PLATFORM=true
WORKSPACES_ROOT Ignored Defines the root directory for all project workspaces

In OSS mode the WORKSPACES_ROOT variable is ignored — Dr. Claw discovers projects from Claude Code / Cursor / Codex session directories under the user's home folder.

Security Checklist

Before deploying Dr. Claw on a network (not just localhost), review the following:

  1. JWT_SECRET — Replace the default with a strong random string. The default value is public and provides zero security.
  2. API_KEY — Consider setting an API key to add an extra authentication layer.
  3. WORKSPACES_ROOT — In Platform mode, ensure this is scoped to a directory you trust. Dr. Claw serves file contents from this tree.
  4. .gitignore — Verify that .env is listed in .gitignore (it is by default) so secrets are never committed.
  5. HTTPS — When exposing Dr. Claw to the internet, place it behind a reverse proxy (e.g. Nginx, Caddy) with TLS termination.

Troubleshooting