DotCraft Full Configuration Reference

This page collects configuration fields, defaults, JSON examples, and advanced references in one place. For first-time setup, read Project Workspace. For product-level explanations, start from the matching Feature page and come back here for exact fields.

DotCraft reads global ~/.craft/config.json first, then overlays workspace .craft/config.json; workspace fields win. String values support $VAR and ${VAR} environment variable placeholders. If a variable is not set, the original placeholder is preserved.

Basic Model and Provider

Field	Description	Default
ProviderId	Current personal provider id. Empty means no provider is selected	Empty
Model	Default model name	gpt-4o-mini
NetworkTimeoutSeconds	Global model request timeout in seconds; providers can override it	600
Providers	Personal model provider dictionary, usually stored in ~/.craft/config.json	Empty
SubagentMaxConcurrency	Maximum concurrent subagents	3
MaxSessionQueueSize	Maximum queued requests per session; 0 means unlimited	3
ConsolidationModel	Memory consolidation model. Empty uses the main model	Empty
DebugMode	Prints untruncated tool arguments in the console	false
EnabledTools	Globally enabled tool names. Empty enables all tools	[]

Personal provider example:

{
  "Providers": {
    "anthropic": {
      "DisplayName": "Anthropic",
      "Protocol": "anthropic",
      "ApiKey": "${ANTHROPIC_API_KEY}"
    },
    "openrouter": {
      "DisplayName": "OpenRouter",
      "Protocol": "openai-chat-completions",
      "ApiKey": "${OPENROUTER_API_KEY}",
      "EndPoint": "https://openrouter.ai/api/v1"
    }
  }
}

Workspace model selection example:

{
  "ProviderId": "anthropic",
  "Model": "claude-sonnet-4-5"
}

Provider object fields:

Field	Description	Default
DisplayName	User-facing provider name; falls back to the provider id when empty	Empty
Protocol	Provider protocol: anthropic, openai-chat-completions, or openai-responses. Empty values and legacy openai are treated as openai-chat-completions.	openai-chat-completions
ApiKey	Provider API key; prefer ${ENV_NAME} environment variable references	Empty
EndPoint	Provider base URL; empty values use the protocol default endpoint	OpenAI protocols: https://api.openai.com/v1; anthropic: https://api.anthropic.com
NetworkTimeoutSeconds	Per-provider request timeout, overriding the global NetworkTimeoutSeconds	Empty
StreamMaxRetries	Per-provider streaming reconnection attempts for dropped or idle provider streams; 0 disables stream retry	5
StreamIdleTimeoutMs	Per-provider idle timeout for streaming responses, in milliseconds	300000

Workspace Memory and Skills

Field	Description	Default
Memory.AutoConsolidateEnabled	Enables automatic long-term memory consolidation	true
Memory.ConsolidateEveryNTurns	Successful turns per thread between long-term memory consolidation attempts	5
Skills.SelfLearning.Enabled	Master switch for agent skill self-learning; off hides skill editing from the model	true
Skills.SelfLearning.MaxSkillContentChars	Max chars for a single SKILL.md written through self-learning	100000
Skills.SelfLearning.MaxSupportingFileBytes	Max bytes for a single supporting file written through self-learning	1048576

Self-learning example:

{
  "Skills": {
    "SelfLearning": {
      "Enabled": true,
      "MaxSkillContentChars": 100000,
      "MaxSupportingFileBytes": 1048576
    }
  }
}

SkillManage(action, ...) reference:

Action	Required parameters	Purpose
create	name, content	Create a new workspace skill
patch	name, oldString, newString	Local patch of SKILL.md or supporting file
edit	name, content	Replace an existing workspace skill's SKILL.md
write_file	name, filePath, fileContent	Write a supporting file
remove_file	name, filePath	Delete a supporting file

create triggers a kind: skill approval; destructive delete operations also require approval. Self-learning writes only the current workspace's skill directory. System and personal skills are read-only, supporting files may only live under scripts/ or assets/, and absolute paths or .. traversal are rejected.

Compaction

Field	Description	Default
Compaction.AutoCompactEnabled	Enables threshold-based auto compaction	true
Compaction.ReactiveCompactEnabled	Enables reactive compaction for prompt_too_long errors	true
Compaction.ContextWindow	Model context window in tokens. When unset, DotCraft infers it from the current effective model	Model catalog value / 256000
Compaction.MaxContextWindow	Upper bound used for inferred model catalog context windows; explicit values are preserved	256000
Compaction.SummaryReserveTokens	Tokens reserved for summary output	20000
Compaction.AutoCompactBufferTokens	Token buffer below the hard limit that triggers auto compaction	13000
Compaction.WarningBufferTokens	Token buffer before auto threshold that emits warning	20000
Compaction.ErrorBufferTokens	Token buffer before auto threshold that emits error	10000
Compaction.ManualCompactBufferTokens	Token buffer below the hard limit where manual /compact remains allowed	3000
Compaction.KeepRecentMinTokens	Minimum recent tail tokens after partial summary	10000
Compaction.KeepRecentMinGroups	Minimum recent API groups after partial summary	3
Compaction.KeepRecentMaxTokens	Maximum recent tail tokens after partial summary	40000
Compaction.MicrocompactEnabled	Enables micro-compaction	true
Compaction.MicrocompactTriggerCount	Compressible tool-result count that triggers micro-compaction	30
Compaction.MicrocompactKeepRecent	Recent tool results kept during micro-compaction	8
Compaction.MicrocompactGapMinutes	Also triggers after this many minutes since last assistant message; 0 disables it	20
Compaction.MaxConsecutiveFailures	Consecutive failures before circuit breaking compaction	3

Model Context-Window Catalog

DotCraft ships a built-in context-window catalog for common models and uses it when Compaction.ContextWindow is not explicitly configured. You can extend or override the catalog with:

• Global: ~/.craft/model-context-windows.json
• Workspace: .craft/model-context-windows.json

{
  "defaultContextWindow": 256000,
  "models": {
    "my-256k-model": 256000,
    "custom-long-context-": 1048576
  }
}

Reasoning and Prompt Caching

Field	Description	Default
Reasoning.Enabled	Requests provider reasoning support	false
Reasoning.Effort	Reasoning depth: None / Low / Medium / High / ExtraHigh	Medium
Reasoning.Output	Reasoning visibility: None / Summary / Full	Full
PromptCaching.Enabled	Inject prompt cache markers for matching models	true
PromptCaching.ModelPatterns	Case-insensitive model name fragments. Empty matches no models	["claude"]
PromptCaching.Placement	Marker placement strategy. Currently only ConversationTail is supported	ConversationTail
PromptCaching.Ttl	Anthropic cache TTL. Empty uses the default 5 minutes; 1h requests the long cache	Empty

Deep-thinking adapter catalog files:

• Global: ~/.craft/model-thinking-adapters.json
• Workspace: .craft/model-thinking-adapters.json

The built-in catalog exposes full reasoning choices for unlisted Anthropic-protocol models, but does not assume they support Anthropic adaptive request shaping. Add anthropicThinking entries for models or endpoints that explicitly support that shape.

{
  "deepThinking": {
    "models": ["deepseek", "mimo", "my-thinking-model-"],
    "endpoints": ["deepseek", "my-thinking-gateway"]
  },
  "anthropicThinking": {
    "adapters": [
      {
        "models": ["my-adaptive-anthropic-model-"],
        "thinking": { "type": "adaptive", "display": "fromReasoningOutput" },
        "outputConfig": { "effort": "fromReasoningEffort" }
      }
    ]
  }
}

Tools Security and Sandbox

Field	Description	Default
Security.BlacklistedPaths	Paths the agent must not access; subpaths are also checked	[]
Tools.File.RequireApprovalOutsideWorkspace	Approve file ops outside workspace	true
Tools.File.MaxFileSize	Max readable file size in bytes	10485760
Tools.File.RipgrepPath	Optional rg path; empty tries DOTCRAFT_RG_PATH, PATH, then fallback	""
Tools.File.SearchTimeoutSeconds	Max GrepFiles content-search time before timeout	30
Tools.Shell.RequireApprovalOutsideWorkspace	Approve shell commands outside workspace	true
Tools.Shell.Timeout	Shell timeout in seconds	300
Tools.Shell.MaxOutputLength	Max shell output length in characters	10000
Tools.Web.MaxChars	Max chars for web fetch	50000
Tools.Web.Timeout	Web request timeout in seconds	300
Tools.Web.SearchMaxResults	Default search result count	5
Tools.Web.SearchProvider	Bing / Exa	Exa
Tools.Lsp.Enabled	Enables built-in LSP tools	false
Tools.Lsp.MaxFileSize	Max LSP file size	10485760
Tools.Sandbox.Enabled	Enable sandbox	false
Tools.Sandbox.Domain	OpenSandbox service address	localhost:5880
Tools.Sandbox.ApiKey	OpenSandbox API key	Empty
Tools.Sandbox.UseHttps	Use HTTPS	false
Tools.Sandbox.Image	Container Docker image	ubuntu:latest
Tools.Sandbox.TimeoutSeconds	Sandbox timeout in seconds	600
Tools.Sandbox.Cpu	Container CPU limit	1
Tools.Sandbox.Memory	Container memory limit	512Mi
Tools.Sandbox.NetworkPolicy	deny / allow / custom	allow
Tools.Sandbox.AllowedEgressDomains	Custom allowed egress domains	[]
Tools.Sandbox.IdleTimeoutSeconds	Idle timeout in seconds	300
Tools.Sandbox.SyncWorkspace	Sync workspace into container	true

Personal local hardening example:

{
  "Security": {
    "BlacklistedPaths": [
      "~/.ssh",
      "~/.gnupg",
      "~/.aws"
    ]
  },
  "Tools": {
    "File": {
      "RequireApprovalOutsideWorkspace": true
    },
    "Shell": {
      "RequireApprovalOutsideWorkspace": true,
      "Timeout": 300
    }
  }
}

Tool allow-list example:

{
  "EnabledTools": ["ReadFile", "GrepFiles", "WebSearch"]
}

OpenSandbox example:

{
  "Tools": {
    "Sandbox": {
      "Enabled": true,
      "Domain": "localhost:5880",
      "Image": "ubuntu:latest",
      "NetworkPolicy": "allow",
      "SyncWorkspace": true
    }
  }
}

Automations Goals and Hooks

Field	Description	Default
Automations.Enabled	Enables the Automations orchestrator	true
Automations.LocalTasksRoot	Local task root. Empty uses .craft/tasks/	Empty
Automations.PollingInterval	Polling interval	00:00:30
Automations.MaxConcurrentTasks	Maximum concurrent local tasks	3
Automations.TurnTimeout	Single-turn timeout	00:30:00
Automations.StallTimeout	Stall timeout without response	00:10:00
Automations.MaxRetries	Maximum retry count	3
Automations.RetryInitialDelay	Initial retry delay	00:00:30
Automations.RetryMaxDelay	Maximum retry delay	00:10:00
Automations.WorktreeRetentionEnabled	Enables retention cleanup for idle automation task worktrees	true
Automations.WorktreeRetentionIdlePeriod	Idle period before a clean automation task worktree is eligible for cleanup	21.00:00:00
Goals.Enabled	Enables goal storage, AppServer methods, goal context injection, usage accounting, and model goal tools	true
Goals.AutoContinueEnabled	Allows active goals to continue when a Thread is idle	true
Hooks.Enabled	Enables Hooks	true
Hooks.Events	Hook lists grouped by event name	[]
Cron.Enabled	Enables Cron scheduled tasks	true
Heartbeat.Enabled	Enables heartbeat service	false
Heartbeat.IntervalSeconds	Check interval in seconds	1800
Heartbeat.NotifyAdmin	Sends results to admin in social channels	true

Automations.WorktreeRetentionIdlePeriod must be at least 14.00:00:00. The retention sweep only removes managed automation task worktrees that are idle, clean, and have no commits ahead of their base.

Automation AppServer methods:

Method	Description
automation/task/list	List local tasks
automation/task/read	Read one local task
automation/task/create	Create a local task
automation/task/run	Run a local task immediately
automation/task/updateBinding	Update or clear thread binding
automation/task/discardWorktree	Remove a task's managed worktree and branch while keeping the task
automation/task/delete	Delete a local task
automation/template/list	List templates
automation/template/save	Save a user template
automation/template/delete	Delete a user template

Goal AppServer methods:

Method	Description
thread/goal/set	Set, replace, pause, or resume a Thread goal
thread/goal/get	Read current Thread goal state
thread/goal/clear	Clear current Thread goal

Hook quick start:

{
  "Hooks": {
    "Enabled": true,
    "Events": {
      "AfterToolCall": [
        {
          "name": "log-tool-call",
          "type": "command",
          "command": "node .craft/hooks/log-tool-call.js",
          "matcher": ".*",
          "timeoutSeconds": 10
        }
      ]
    }
  }
}

Hook item fields:

Field	Description
name	Hook name for logs and troubleshooting
type	Supports "command"
command	Shell command to run
matcher	Regex for matching tool names. Empty matches all tool-related events
timeoutSeconds	Hook timeout

Lifecycle events:

Event	Purpose
BeforeToolCall	Check or block before tool calls
AfterToolCall	Log, format, or notify after tool calls
BeforeTurn	Prepare context before an Agent turn
AfterTurn	Record results or notify after an Agent turn
BeforeAutomationTask	Check before an automation task runs
AfterAutomationTask	Sync state after an automation task completes

Tool-related Hook stdin usually includes:

{
  "event": "BeforeToolCall",
  "workspace": "F:\\project",
  "sessionId": "thread-id",
  "toolName": "Exec",
  "arguments": {
    "command": "dotnet test"
  }
}

Turn-related Hook stdin usually includes:

{
  "event": "AfterTurn",
  "workspace": "F:\\project",
  "sessionId": "thread-id",
  "summary": "Agent completed the turn"
}

Exit code semantics:

Exit code	Meaning
0	Success, continue
Non-zero	Hook failed; Before* events can block the current operation

Matcher examples:

matcher	Matches
WriteFile|EditFile	File writes and edits
Exec	Shell commands
.*	All tools

Entry Points and Services

Field	Description	Default
Acp.Enabled	Enables ACP mode	false
DashBoard.Enabled	Enables Dashboard	false
DashBoard.Host	Dashboard listen address	127.0.0.1
DashBoard.Port	Dashboard listen port	8080
Gateway.Enabled	Enables Gateway Host	false
AppServer.Mode	AppServer transport mode, such as stdio or WebSocket	Empty
AppServer.WebSocket.Host	WebSocket listen host	127.0.0.1
AppServer.WebSocket.Port	WebSocket listen port	9100
AppServer.WebSocket.Token	Token required by remote WebSocket clients	Empty
ExternalChannels	External channel registration map	{}

Dashboard example:

{
  "DashBoard": {
    "Enabled": true,
    "Host": "127.0.0.1",
    "Port": 8080
  }
}

External channel registration example:

{
  "AppServer": {
    "Mode": "WebSocket",
    "WebSocket": {
      "Host": "127.0.0.1",
      "Port": 9100,
      "Token": ""
    }
  },
  "ExternalChannels": {
    "qq": {
      "enabled": true,
      "transport": "subprocess",
      "builtinModule": "channel-qq"
    },
    "wecom": {
      "enabled": true,
      "transport": "websocket"
    }
  }
}

Platform connections, allowlists, and approval timeouts live in adapter-specific files such as .craft/qq.json and .craft/wecom.json.

Plugins MCP and LSP

Field	Description	Default
Plugins.PluginRoots	Extra plugin root directories maintained outside .craft/plugins/	[]
McpServers	MCP server configuration map	{}
Tools.DeferredLoading.Strategy	Deferred tool loading strategy: Off, Auto, Simulated, or Native	Auto
Tools.DeferredLoading.AlwaysLoadedTools	MCP tool names always loaded upfront	[]
Tools.DeferredLoading.DeferThreshold	Minimum MCP tool count before MCP tools are deferred	10
Tools.DeferredLoading.MaxSearchResults	Maximum deferred tool search results per query	5
LspServers	LSP server configuration map	{}
Tools.Lsp.Enabled	Enables built-in LSP tools	false

External plugin root example:

{
  "Plugins": {
    "PluginRoots": ["./samples/plugins"]
  }
}

MCP example:

{
  "McpServers": {
    "everything": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-everything"]
    }
  },
  "Tools": {
    "DeferredLoading": {
      "Strategy": "Auto",
      "DeferThreshold": 10
    }
  }
}

With Tools.DeferredLoading.Strategy = Auto, openai-responses uses native client-executed tool_search, while chat-completions and Anthropic use simulated SearchTools.

SubAgent and External CLI Profiles

For the beginner path, read SubAgents.

Field	Description	Default
SubAgent.MaxDepth	Maximum session-backed SubAgent spawn depth; the first child is depth 1	1
SubAgent.Model	Model used by DotCraft native SubAgents; empty inherits the current thread's effective main model	Empty
SubAgent.MinWaitTimeoutMs	Minimum accepted WaitAgent.timeoutMs value in milliseconds	15000
SubAgent.DefaultWaitTimeoutMs	WaitAgent.timeoutMs used when the tool call omits a timeout	60000
SubAgent.MaxWaitTimeoutMs	Maximum accepted WaitAgent.timeoutMs value in milliseconds	3600000
SubAgent.EnableExternalCliSessionResume	Allows external CLI profiles that support resume to reuse saved external sessions	false
SubAgent.DisabledProfiles	SubAgent profile names hidden and disabled for this workspace	[]
SubAgent.Roles	Workspace-defined SubAgent roles; entries with built-in names override built-in roles	[]

Role example:

{
  "SubAgent": {
    "MaxDepth": 2,
    "Roles": [
      {
        "Name": "docs-explorer",
        "Description": "Read-only documentation and code explorer.",
        "ToolAllowList": ["ReadFile", "GrepFiles", "FindFiles", "WebSearch", "WebFetch", "SkillView"],
        "AgentControlToolAccess": "Disabled",
        "PromptProfile": "subagent-light",
        "Instructions": "Inspect files and web sources only. Do not edit files, execute shell commands, manage skills, or spawn agents."
      }
    ]
  }
}

Fields inside each SubAgent.Roles entry:

Field	Description
Name	Role name, also the value used by SpawnAgent.agentRole
Description	Short role description exposed to the main Agent
ToolAllowList	Exact tool allow-list; empty means no additional restriction on eligible tools
ToolDenyList	Exact tool deny-list removed after the tool set is assembled
AgentControlToolAccess	AgentTools policy: Disabled / Full / AllowList
AllowedAgentControlTools	AgentTools names allowed when AgentControlToolAccess is AllowList
PromptProfile	Native SubAgent prompt profile: subagent-light / full
Instructions	Role instructions appended to the SubAgent prompt
Mode	Optional mode override
Model	Optional model override
OverrideBasePrompt	Replaces the base prompt with Instructions; by default instructions are appended

Custom external CLI profiles live under SubAgentProfiles. Workspace config overrides same-named global profiles.

{
  "SubAgent": {
    "EnableExternalCliSessionResume": true
  },
  "SubAgentProfiles": {
    "my-cli": {
      "runtime": "cli-oneshot",
      "bin": "my-cli",
      "workingDirectoryMode": "workspace",
      "inputMode": "arg",
      "outputFormat": "text",
      "supportsResume": true,
      "resumeArgTemplate": "--resume {sessionId}",
      "resumeSessionIdJsonPath": "session_id"
    }
  }
}

Fields inside each SubAgentProfiles entry:

Field	Description
runtime	Runtime type; external short-process CLIs use cli-oneshot
bin	CLI executable name or absolute path
args	Fixed argument list
workingDirectoryMode	workspace / specified
inputMode	stdin / arg / arg-template / env
inputArgTemplate	Template for arg-template mode
inputEnvKey	Env-var name receiving task text in env mode
env	Fixed env vars injected into the subprocess
envPassthrough	Names of env vars to copy from parent
outputFormat	text or json
outputJsonPath	JSON path to extract the final result in json mode
readOutputFile	Prefer reading the output file as the final result
outputFileArgTemplate	Output-file argument template, supports {path}
supportsResume	Allow DotCraft to store and reuse the external session id
resumeArgTemplate	Resume argument template, supports {sessionId}
resumeSessionIdJsonPath	JSON path to extract session id from stdout
resumeSessionIdRegex	Regex fallback when stdout is not a single JSON object
timeout	Per-run timeout in seconds
maxOutputBytes	Maximum captured output bytes
trustLevel	trusted / prompt / restricted
permissionModeMapping	Map DotCraft approval modes to CLI arguments

Vendor headless notes:

Profile	Behavior
cursor-cli	DotCraft injects -p --output-format json and appends --resume {sessionId} when resuming
codex-cli	DotCraft injects exec plus output-file arguments; resume becomes exec resume {sessionId}

Custom Commands

CustomCommands stores reusable prompts or workflows as commands. Command content usually lives under workspace .craft/commands/ or the corresponding configuration entry, then can be reused from CLI, Desktop, and other entry points.

Related docs

• Project Workspace — first-time setup and the .craft/ layout
• AppServer Mode — AppServer.* / CLI.* fields in context
• Settings Lifecycle — when a changed field takes effect