froe

Configuration reference

User configuration ~/.config/froe/config.json

Read configuration from five layers.

Every session merges the layers below from lowest to highest precedence. A later layer overrides earlier values; object and array settings are replaced, not merged field by field.

Built-in defaults
The starting values compiled into Froe, such as the default model and 40-turn run bound. User or Workspace configuration may override the keys they are allowed to set.
$XDG_CONFIG_HOME/froe/config.json
User configuration, or ~/.config/froe/config.json when the environment variable is unset. It applies to every Workspace and may set any supported key.
.froe/config.jsonworkspace
Workspace configuration inside the Workspace root. It may set only model and limits; every other key is rejected here.
--config <path>
An explicit user-controlled JSON file loaded for one invocation. It merges above Workspace configuration and may set any supported key.
Invocation overrides
CLI flags such as --model, --reasoning, --base-url, --max-turns, and --no-update rank highest. Embedders pass the same values as overrides to openFroeSession.
  • Editors may validate a file against the machine-readable froe.config.schema.json schema by setting $schema in the file itself.
  • The schema ships with the npm package and lives in the repository root, alongside this reference.

Set persistent defaults.

Keys marked workspace file may also live in .froe/config.json. All other keys are user configuration only.

provider
Must be "openai"; it is the only provider in the current release.
baseURL
An OpenAI-compatible API endpoint. When absent, Froe uses the OpenAI default or OPENAI_BASE_URL.
autoUpdate
Automatic update checks for the npm package. Default true; set false or pass --no-update to disable.
modelworkspace file
The OpenAI-compatible model used for runs. Default gpt-6-astra. --model overrides one invocation; /model changes the current conversation without saving configuration.
reasoning
Reasoning effort: none, low, medium, high, xhigh, or max. Default medium.
compactThresholdTokens
Token threshold for OpenAI server-side context compaction. Default 200000; null disables compaction for endpoints that do not support it.
maxTurns
Maximum model turns per bounded run, including each message in an interactive conversation. Default 40; positive integer.
logging
Run record verbosity: metadata or full. Default metadata.
limitsworkspace file
Positive per-action limits: readLines 400, readBytes 131072, searchResults 200, commandOutputBytes 131072, and commandTimeoutMs 120000. Workspace configuration may set any subset.
commandEnv
Environment variable names passed to spawned commands, such as TAVILY_API_KEY. Default empty; workspace configuration cannot grant command environment access.
extraInstructions
Standing instructions appended to every run's system prompt as non-empty strings. They outrank recognized AGENTS.md or CLAUDE.md project instructions but never the user's explicit task. Default empty; user configuration only.
mcpServers
MCP servers contributing tools and context, keyed by name. Each entry is a stdio server with command and optional args, or a remote server with url. Default empty; froe mcp add writes entries here.

A Workspace cannot set most keys.

A Workspace is code Froe runs on, so its configuration is treated as project-owned content rather than trusted user choice.

Configuration authority

  • .froe/config.json may contain only model and limits.
  • An explicit --config file is user-controlled and holds the same authority as user configuration, regardless of where it is stored.
  • Project-owned guidance belongs in recognized instruction files such as AGENTS.md; repository content is data, not instructions.

Credentials and environment

  • Connection and search keys are never read from Workspace configuration or .env files. They are stored in an owner-only credentials file or supplied through the environment.
  • Spawned commands receive a small base environment (PATH, home, temp, and locale variables) plus names explicitly listed in commandEnv. Provider keys such as OPENAI_API_KEY and TAVILY_API_KEY are never forwarded.