"description": "Top-level Forge configuration merged from all sources (defaults, file,\nenvironment).",
"type": "object",
"properties": {
"auto_dump": {
"description": "Format used when automatically creating a session dump after task\ncompletion; disabled when absent.",
"anyOf": [
{
"$ref": "#/$defs/AutoDumpFormat"
},
{
"type": "null"
}
]
},
"auto_open_dump": {
"description": "Whether to automatically open HTML dump files in the browser after\ncreation.",
"type": "boolean",
"default": false
},
"commit": {
"description": "Model and provider configuration used for commit message generation.",
"anyOf": [
{
"$ref": "#/$defs/ModelConfig"
},
{
"type": "null"
}
]
},
"compact": {
"description": "Context compaction settings applied to all agents; falls back to each\nagent's individual setting when absent.",
"anyOf": [
{
"$ref": "#/$defs/Compact"
},
{
"type": "null"
}
]
},
"custom_history_path": {
"description": "Path to the conversation history file; defaults to the global history\nlocation when absent.",
"type": [
"string",
"null"
]
},
"debug_requests": {
"description": "Directory where debug request files are written; disabled when absent.",
"type": [
"string",
"null"
]
},
"http": {
"description": "HTTP client settings including proxy, TLS, and timeout configuration.",
"anyOf": [
{
"$ref": "#/$defs/HttpConfig"
},
{
"type": "null"
}
]
},
"max_conversations": {
"description": "Maximum number of conversations shown in the conversation list.",
"type": "integer",
"format": "uint",
"default": 0,
"minimum": 0
},
"max_extensions": {
"description": "Maximum number of file extensions included in the agent system prompt.",
"type": "integer",
"format": "uint",
"default": 0,
"minimum": 0
},
"max_fetch_chars": {
"description": "Maximum number of characters returned from a URL fetch.",
"type": "integer",
"format": "uint",
"default": 0,
"minimum": 0
},
"max_file_read_batch_size": {
"description": "Maximum number of files read in a single batch operation.",
"type": "integer",
"format": "uint",
"default": 0,
"minimum": 0
},
"max_file_size_bytes": {
"description": "Maximum file size in bytes permitted for read operations.",
"type": "integer",
"format": "uint64",
"default": 0,
"minimum": 0
},
"max_image_size_bytes": {
"description": "Maximum image file size in bytes permitted for read operations.",
"type": "integer",
"format": "uint64",
"default": 0,
"minimum": 0
},
"max_line_chars": {
"description": "Maximum number of characters per line when reading a file.",
"type": "integer",
"format": "uint",
"default": 0,
"minimum": 0
},
"max_parallel_file_reads": {
"description": "Maximum number of files read concurrently during batch operations.",
"type": "integer",
"format": "uint",
"default": 0,
"minimum": 0
},
"max_read_lines": {
"description": "Maximum number of lines read from a file in a single operation.",
"type": "integer",
"format": "uint64",
"default": 0,
"minimum": 0
},
"max_requests_per_turn": {
"description": "Maximum number of requests that can be made in a single turn.",
"type": [
"integer",
"null"
],
"format": "uint",
"minimum": 0
},
"max_search_lines": {
"description": "Maximum number of lines returned by a single file search operation.",
"type": "integer",
"format": "uint",
"default": 0,
"minimum": 0
},
"max_search_result_bytes": {
"description": "Maximum number of bytes returned by a single file search operation.",
"type": "integer",
"format": "uint",
"default": 0,
"minimum": 0
},
"max_sem_search_results": {
"description": "Maximum number of candidate results returned from the initial semantic\nsearch vector query.",
"type": "integer",
"format": "uint",
"default": 0,
"minimum": 0
},
"max_stdout_line_chars": {
"description": "Maximum number of characters per line in shell command output.",
"type": "integer",
"format": "uint",
"default": 0,
"minimum": 0
},
"max_stdout_prefix_lines": {
"description": "Maximum number of lines captured from the leading portion of shell\ncommand output.",
"type": "integer",
"format": "uint",
"default": 0,
"minimum": 0
},
"max_stdout_suffix_lines": {
"description": "Maximum number of lines captured from the trailing portion of shell\ncommand output.",
"type": "integer",
"format": "uint",
"default": 0,
"minimum": 0
},
"max_tokens": {
"description": "Maximum tokens the model may generate per response for all agents\n(1–100,000).",
"type": [
"integer",
"null"
],
"format": "uint32",
"minimum": 0
},
"max_tool_failure_per_turn": {
"description": "Maximum tool failures per turn before the orchestrator forces\ncompletion.",
"type": [
"integer",
"null"
],
"format": "uint",
"minimum": 0
},
"model_cache_ttl_secs": {
"description": "Time-to-live in seconds for the cached model API list.",
"type": "integer",
"format": "uint64",
"default": 0,
"minimum": 0
},
"restricted": {
"description": "Whether restricted mode is active; when enabled, tool execution requires\nexplicit permission grants.",
"type": "boolean",
"default": false
},
"retry": {
"description": "Retry settings applied at the system level to all IO operations.",
"anyOf": [
{
"$ref": "#/$defs/RetryConfig"
},
{
"type": "null"
}
]
},
"sem_search_top_k": {
"description": "Number of top results retained after re-ranking in semantic search.",
"type": "integer",
"format": "uint",
"default": 0,
"minimum": 0
},
"services_url": {
"description": "Base URL of the Forge services API used for semantic search and\nindexing.",
"type": "string",
"default": ""
},
"session": {
"description": "Default model and provider configuration used when not overridden by\nindividual agents.",
"anyOf": [
{
"$ref": "#/$defs/ModelConfig"
},
{
"type": "null"
}
]
},
"suggest": {
"description": "Model and provider configuration used for shell command suggestion\ngeneration.",
"anyOf": [
{
"$ref": "#/$defs/ModelConfig"
},
{
"type": "null"
}
]
},
"temperature": {
"description": "Output randomness for all agents; lower values are deterministic, higher\nvalues are creative (0.0–2.0).",
"anyOf": [
{
"$ref": "#/$defs/double"
},
{
"type": "null"
}
]
},
"tool_supported": {
"description": "Whether tool use is supported in the current environment; when false,\nall tool calls are disabled.",
"type": "boolean",
"default": false
},
"tool_timeout_secs": {
"description": "Maximum time in seconds a single tool call may run before being\ncancelled.",
"type": "integer",
"format": "uint64",
"default": 0,
"minimum": 0
},
"top_k": {
"description": "Top-k vocabulary cutoff for all agents; restricts sampling to the k\nhighest-probability tokens (1–1000).",
"type": [
"integer",
"null"
],
"format": "uint32",
"minimum": 0
},
"top_p": {
"description": "Nucleus sampling threshold for all agents; limits token selection to the\ntop cumulative probability mass (0.0–1.0).",
"anyOf": [
{
"$ref": "#/$defs/double"
},
{
"type": "null"
}
]
},
"updates": {
"description": "Configuration for automatic Forge updates.",
"anyOf": [
{
"$ref": "#/$defs/Update"
},
{
"type": "null"
}
]
}
},
"$defs": {
"AutoDumpFormat": {
"description": "The output format used when auto-dumping a conversation on task completion.",
"oneOf": [
{
"description": "Dump as a JSON file",
"type": "string",
"const": "json"
},
{
"description": "Dump as an HTML file",
"type": "string",
"const": "html"
}
]
},
"Compact": {
"description": "Configuration for automatic context compaction for all agents",
"type": "object",
"properties": {
"eviction_window": {
"description": "Maximum percentage of the context that can be summarized during\ncompaction. Valid values are between 0.0 and 1.0, where 0.0 means no\ncompaction and 1.0 allows summarizing all messages. Works alongside\nretention_window - the more conservative limit (fewer messages to\ncompact) takes precedence.",
"$ref": "#/$defs/double",
"default": 0.0
},
"max_tokens": {
"description": "Maximum number of tokens to keep after compaction",
"type": [
"integer",
"null"
],
"format": "uint",
"minimum": 0
},
"message_threshold": {
"description": "Maximum number of messages before triggering compaction",
"type": [
"integer",
"null"
],
"format": "uint",
"minimum": 0
},
"model": {
"description": "Model ID to use for compaction, useful when compacting with a\ncheaper/faster model. If not specified, the root level model will be\nused.",
"type": [
"string",
"null"
]
},
"on_turn_end": {
"description": "Whether to trigger compaction when the last message is from a user",
"type": [
"boolean",
"null"
]
},
"retention_window": {
"description": "Number of most recent messages to preserve during compaction.\nThese messages won't be considered for summarization. Works alongside\neviction_window - the more conservative limit (fewer messages to\ncompact) takes precedence.",
"type": "integer",
"format": "uint",
"default": 0,
"minimum": 0
},
"token_threshold": {
"description": "Maximum number of tokens before triggering compaction",
"type": [
"integer",
"null"
],
"format": "uint",
"minimum": 0
},
"turn_threshold": {
"description": "Maximum number of conversation turns before triggering compaction",
"type": [
"integer",
"null"
],
"format": "uint",
"minimum": 0
}
}
},
"HttpConfig": {
"description": "HTTP client configuration.",
"type": "object",
"properties": {
"accept_invalid_certs": {
"description": "Accept invalid certificates",
"type": "boolean"
},
"adaptive_window": {
"description": "Adaptive window sizing for improved flow control",
"type": "boolean"
},
"connect_timeout_secs": {
"type": "integer",
"format": "uint64",
"minimum": 0
},
"hickory": {
"type": "boolean"
},
"keep_alive_interval_secs": {
"description": "Keep-alive interval in seconds",
"type": [
"integer",
"null"
],
"format": "uint64",
"minimum": 0
},
"keep_alive_timeout_secs": {
"description": "Keep-alive timeout in seconds",
"type": "integer",
"format": "uint64",
"minimum": 0
},
"keep_alive_while_idle": {
"description": "Keep-alive while connection is idle",
"type": "boolean"
},
"max_redirects": {
"type": "integer",
"format": "uint",
"minimum": 0
},
"max_tls_version": {
"description": "Maximum TLS protocol version to use",
"anyOf": [
{
"$ref": "#/$defs/TlsVersion"
},
{
"type": "null"
}
]
},
"min_tls_version": {
"description": "Minimum TLS protocol version to use",
"anyOf": [
{
"$ref": "#/$defs/TlsVersion"
},
{
"type": "null"
}
]
},
"pool_idle_timeout_secs": {
"type": "integer",
"format": "uint64",
"minimum": 0
},
"pool_max_idle_per_host": {
"type": "integer",
"format": "uint",
"minimum": 0
},
"read_timeout_secs": {
"type": "integer",
"format": "uint64",
"minimum": 0
},
"root_cert_paths": {
"description": "Paths to root certificate files",
"type": [
"array",
"null"
],
"items": {
"type": "string"
}
},
"tls_backend": {
"$ref": "#/$defs/TlsBackend"
}
},
"required": [
"connect_timeout_secs",
"read_timeout_secs",
"pool_idle_timeout_secs",
"pool_max_idle_per_host",
"max_redirects",
"hickory",
"tls_backend",
"adaptive_window",
"keep_alive_timeout_secs",
"keep_alive_while_idle",
"accept_invalid_certs"
]
},
"ModelConfig": {
"description": "Pairs a provider and model together for a specific operation.",
"type": "object",
"properties": {
"model_id": {
"description": "The model to use for this operation.",
"type": [
"string",
"null"
]
},
"provider_id": {
"description": "The provider to use for this operation.",
"type": [
"string",
"null"
]
}
}
},
"RetryConfig": {
"description": "Configuration for retry mechanism.",
"type": "object",
"properties": {
"backoff_factor": {
"description": "Backoff multiplication factor for each retry attempt",
"type": "integer",
"format": "uint64",
"minimum": 0
},
"initial_backoff_ms": {
"description": "Initial backoff delay in milliseconds for retry operations",
"type": "integer",
"format": "uint64",
"minimum": 0
},
"max_attempts": {
"description": "Maximum number of retry attempts",
"type": "integer",
"format": "uint",
"minimum": 0
},
"max_delay_secs": {
"description": "Maximum delay between retries in seconds",
"type": [
"integer",
"null"
],
"format": "uint64",
"minimum": 0
},
"min_delay_ms": {
"description": "Minimum delay in milliseconds between retry attempts",
"type": "integer",
"format": "uint64",
"minimum": 0
},
"status_codes": {
"description": "HTTP status codes that should trigger retries",
"type": "array",
"items": {
"type": "integer",
"format": "uint16",
"maximum": 65535,
"minimum": 0
}
},
"suppress_errors": {
"description": "Whether to suppress retry error logging and events",
"type": "boolean"
}
},
"required": [
"initial_backoff_ms",
"min_delay_ms",
"backoff_factor",
"max_attempts",
"status_codes",
"suppress_errors"
]
},
"TlsBackend": {
"description": "TLS backend option.",
"type": "string",
"enum": [
"default",
"rustls"
]
},
"TlsVersion": {
"description": "TLS version enum for configuring TLS protocol versions.",
"type": "string",
"enum": [
"1.0",
"1.1",
"1.2",
"1.3"
]
},
"Update": {
"description": "Configuration for automatic forge updates",
"type": "object",
"properties": {
"auto_update": {
"description": "Whether to automatically install updates without prompting",
"type": [
"boolean",
"null"
]
},
"frequency": {
"description": "How frequently forge checks for updates",
"anyOf": [
{
"$ref": "#/$defs/UpdateFrequency"
},
{
"type": "null"
}
]
}
}
},
"UpdateFrequency": {
"description": "Frequency at which forge checks for updates",