Configuration

ClaudeControl can be configured through the Settings page in the dashboard, environment variables, and config files.

Runtime configuration

These settings are available in the Settings page and are persisted to ~/.claudecontrol/config.json:

Setting	Default	Description
maxTurns	12	Maximum conversation turns per agent query
maxBudgetUsd	--	Per-agent cost limit in USD. Agent stops when exceeded
model	--	Default model override (e.g. claude-sonnet-4-20250514)
fallbackModel	--	Model to use when the primary model fails
enableSubagents	true	Allow agents to use the Agent tool (SDK subagents)
subagentLimit	3	Maximum concurrent SDK subagents per agent
subagentPromptMaxChars	3000	Max chars for subagent prompts
contextMaxChars	8000	Max chars for context sent to SDK
contextWindowSize	200000	Token context window size passed to the SDK

Environment variables

Variable	Default	Description
PORT	22609	HTTP server port
CLAUDE_PATH	auto-detected	Absolute path to the claude CLI binary
CC_DATA_DIR	~/.claudecontrol/data/	Directory for workspace data, logs, and attachments

Example:

PORT=3000 CLAUDE_PATH=/usr/local/bin/claude claudecontrol

Data directory

All persistent data is stored under ~/.claudecontrol/:

~/.claudecontrol/
  config.json          # App config (runtime settings, PIN hash, VAPID keys)
  data/                # Default data directory
    <workspace-id>/
      agents.json      # Agent state
      log/             # Per-agent conversation logs
      attachments/     # Uploaded file attachments
      raw/             # Raw SDK message logs

You can change the data directory from the Settings page or by setting CC_DATA_DIR.

PIN authentication

Protect the dashboard with a 4-8 character PIN:

1. Open Settings in the dashboard.
2. Enter a PIN in the security section and save.

When a PIN is set:

• The dashboard shows a login screen on load.
• WebSocket connections require a ?token=<hash> query parameter.
• API requests require an Authorization: Bearer <hash> header.

Remove the PIN from Settings or via DELETE /api/settings/pin.

Push notifications

ClaudeControl supports browser push notifications for agent events (completion, errors, permission requests). Enable them from the Settings page. VAPID keys are auto-generated on first run.

Local development environment

When running frontend and backend separately during development, create a frontend/.env file:

VITE_API_URL=http://localhost:12000
VITE_DEV_PORT=12500

Variable	Default	Description
VITE_API_URL	--	Backend API URL for the Vite dev server proxy
VITE_DEV_PORT	--	Port for the Vite dev server