Introducing a new way to review your PRs.

Read the announcement

alishahryar1 / free-claude-code

Use Claude Code, Codex, Antigravity, VSCode, Pi, and OpenCode (and 6 other harnesses) for free (1.3B+ free tokens) from your terminal, app, IDE, or phone, and now from the browser with native browser sessions (multi-harness + multi-model) like OpenClaw (voice supported + ToS friendly)

View on GitHub

28 documents · Updated Nov 20, 2026

docs / configuration-lifecycle

Configuration lifecycle

Configuration gives the server and its provider clients one validated, immutable view of user settings. It joins safe defaults with a managed user file and process environment values, then carries those values into model routing, reasoning, server URLs, custom providers, and the local Admin surface. See Configuration and runtime for the wider runtime view, Runtime startup and provider management for startup and provider replacement, Accounts, models, and reasoning for request-level model behavior, and Provider runtime and discovery for provider readiness.

Configuration sources

The configuration flow turns environment text into a typed Settings value. The managed file provides persistent user choices, while the process environment can provide values for one launch or take precedence over the managed file.

flowchart LR
    A[Process environment] --> C[Settings resolution]
    B[Managed ~/.fcc/.env] --> C
    D[Built-in defaults] --> C
    C --> E[Validated Settings]
    E --> F[Runtime and provider clients]
    E --> G[Model routing and Admin view]

Persistent and process values

The loader reads the managed file at ~/…/.env and combines it with the live process environment. A process value normally wins over the managed value. The API/CLI auth token has one extra rule: a non-empty managed token remains the stored token even when a process token is present, while an empty process token does not erase it. The loader records each effective field as default, managed_env, or process, so the Admin UI can explain who owns the value.

The process-wide settings value is cached after resolution. A committed Admin change clears this cache so later work can see the new settings. A commit re-reads the managed file while holding the storage lock and compares the expected snapshot, so it does not replace newer state. The managed store also repairs invalid saved provider proxy values when the process does not provide its own value. A stale editor receives a configuration conflict instead of silently overwriting a newer change.

The shared path service places user configuration under ~/.fcc. It defines the managed environment file and its cross-process lock, plus separate paths for launcher data, Code session state, messaging state, logs, model catalogs, and provider authentication. These paths keep persistent configuration and related runtime state in one user-owned area while giving each state type its own file or directory.

References: src/…/loader.py• L33-57 src/…/loader.py• L60-148 src/…/loader.py• L151-204 src/…/errors.py• L1-5 src/…/paths.py• L24-55 src/…/paths.py• L68-100

Typed settings

src/…/settings.py defines the validated, immutable settings contract. It converts environment strings into values used by the rest of the system and rejects values that would make a provider, route, server, or feature unsafe to use. A published settings snapshot cannot be changed in place; a change must produce another validated snapshot.

The settings contract covers these broad areas:

AreaRole
Provider accessAPI key lists, account-backed access, custom endpoints, and proxies
Custom providersUser-defined provider IDs, display names, endpoints, credentials, and reasoning formats
Model useDefault model, Claude tier overrides, and ordered fallbacks
RuntimeServer bind address, port, API authentication, limits, and timeouts
Messaging and voicePlatform access, message limits, voice transcription, and model choice
Web tools and diagnosticsURL schemes, private-network policy, log levels, and sensitive-data logging flags
Provider discoveryLocal endpoint settings and provider-specific setup values

Blank optional values become unset. Provider credentials accept one or more ordered keys, reject blank or duplicate entries, and use the first key for provider access. Model values must use a supported provider prefix and a non-empty model name. A custom provider extends the supported provider IDs after its definition is decoded and must have a unique ID and display name. Cross-field checks also protect dependent features, such as NVIDIA NIM voice transcription without its required key.

Shared constants keep important defaults consistent across the settings model and provider-facing code. They include the default model, the client context allocation, the HTTP connection timeout, and the default Anthropic output limit. Diagnostic settings feed the structured JSON log sink, which also receives standard-library and selected third-party log records.

References: src/…/settings.py• L27-105 src/…/settings.py• L383-408 src/…/settings.py• L582-632 src/…/settings.py• L672-706 src/…/settings.py• L750-865 src/…/api_keys.py• L9-59 src/…/constants.py• L1-12 src/…/logging_config.py• L68-137

Configuration migration

Migration moves older dotenv (environment-file) state into one user-owned file. It runs during settings resolution under a cross-process lock, which prevents two server processes from rewriting the managed state at the same time.

The migration path is:

  1. Use the existing ~/…/.env when it exists.
  2. Otherwise look for supported legacy user files or a verified checkout .env.
  3. Import a file named by FCC_ENV_FILE when it is separate from the managed file.
  4. Rename retired keys and translate old values into the current names.
  5. Normalize old single-key credentials and custom-provider credential members into the current ordered-key form.
  6. Remove retired keys and empty recognized settings.
  7. Write schema version 2 to ~/…/.env.
flowchart TD
    A[Legacy or managed dotenv files] --> B[Parse and migrate keys]
    B --> C[Normalize credentials and model references]
    C --> D[Filter recognized settings]
    D --> E[Add schema version 2]
    E --> F[Atomic managed-file write]
    F --> G[Typed settings resolution]

The migration includes old Hugging Face and reasoning names. It also moves OpenCode Zen names to their current provider and proxy names and repairs retired provider model references. The set of keys that can move into managed state follows the settings aliases and the provider catalog, including catalog-derived smoke-test keys. A current managed file remains unchanged when its schema version is supported unless a model repair is needed. An unsupported schema stops loading instead of silently changing data. Unknown keys are not used as settings, but the managed writer preserves them so migration does not discard unrelated user values. Secret values are masked in previews and the managed file is written with restricted permissions on supported systems.

References: src/…/env_migrations.py• L32-47 src/…/env_migrations.py• L72-130 src/…/env_migrations.py• L138-190 src/…/env_migrations.py• L193-264 src/…/env_migrations.py• L267-307 src/…/env_migrations.py• L319-385 src/…/paths.py• L5-7 src/…/paths.py• L16-17 src/…/paths.py• L30-39 src/…/paths.py• L58-65

Provider and model references

Provider configuration connects a model name to an access method and an upstream endpoint. The provider catalog is the shared description of provider IDs, credentials, default base URLs, custom URL settings, proxies, and whether access comes from a connected account or direct configuration.

Provider endpoints

The catalog owns default upstream URL values for remote and local providers. Settings can replace selected endpoints, such as Azure OpenAI, Bedrock, TokenRouter, NaraRoute, LM Studio, Llama.cpp, and Ollama. Each catalog entry also states whether access uses direct configuration or a connected account, which settings make the provider ready, and whether the provider is local. The catalog order becomes the shared order for provider discovery and user-facing provider lists. Custom providers sit outside this fixed catalog and add user-owned provider IDs to the settings snapshot.

The Admin provider manifest derives credential, base URL, and proxy fields from this catalog. It combines providers that share one credential setting into one Admin field, while adding provider-specific setup fields such as Cloudflare account ID and Vertex project and location. Presentation overrides refine labels, help text, or restart behavior without creating a second provider registry. Catalog metadata also supplies provider-specific smoke-test fields.

The local server has a separate browser URL model. src/…/server_urls.py builds the proxy root and Admin URL from the configured host and port. A wildcard bind address is changed to a loopback address for displayed browser links, and an IPv6 host is formatted for a URL. The same helpers compare equivalent loopback URLs and add the canonical /v1 API suffix for client launchers. This keeps a server that listens on all interfaces from showing an unusable browser address while keeping local client endpoints consistent.

References: src/…/provider_catalog.py• L10-31 src/…/provider_catalog.py• L108-143 src/…/provider_catalog.py• L146-824 src/…/provider_catalog.py• L826-837 src/…/provider_manifest.py• L356-373 src/…/provider_manifest.py• L376-402 src/…/provider_manifest.py• L405-486 src/…/provider_manifest.py• L489-504 src/…/manifest.py• L568-584 src/…/server_urls.py• L1-55 src/…/admin_routes.py• L144-152 src/…/admin_routes.py• L266-312

Model references

A model reference is a string in the form provider/model. The provider prefix selects the provider type, while the remaining part identifies the upstream model. The default model supplies the target for Claude-compatible names that have no tier-specific override. The provider prefix can name either a catalog provider or a configured custom provider.

Claude model tiers can each point to a different provider/model reference. A fallback list adds ordered alternate references after the primary target fails in a retryable way. Each fallback can carry its own reasoning preference and API-key selection. Fallbacks can be read from a compact list or JSON form, then become one validated ordered value. The model reference helper collects primary, tier, and fallback values, removes duplicates, and exposes the provider and model parts for discovery and routing. It also removes references for retired providers during configuration migration and settings composition without changing the source precedence of other values.

References: src/…/model_refs.py• L18-44 src/…/model_refs.py• L47-114 src/…/model_refs.py• L117-181 src/…/settings.py• L43-53 src/…/settings.py• L83-105 src/…/settings.py• L383-408 src/…/routing.py• L61-131

Custom provider definitions

Custom provider definitions let an administrator add an OpenAI-compatible or Anthropic-compatible endpoint without changing the built-in provider catalog. Each definition has a generated custom_... ID, a unique display name, an HTTP or HTTPS base URL, ordered credentials, and optional reasoning formats. The settings snapshot exposes these definitions as provider IDs, so model references can route to them like built-in providers.

The definition also states the upstream API format, the reasoning format, the reasoning history format, and known model IDs. Validation keeps these choices compatible. The encoded value is a JSON array stored under FCC_CUSTOM_PROVIDERS, and secret keys are not included in normal model representations. Admin edits treat credential rows as a separate ordered-key operation, so a masked row can retain its saved value without exposing it.

References: src/…/custom_providers.py• L16-30 src/…/custom_providers.py• L33-112 src/…/custom_providers.py• L114-128 src/…/settings.py• L66-105 src/…/custom_providers.py• L18-102 src/…/credentials.py• L15-137

Reasoning configuration

Reasoning configuration controls how much model thinking the gateway requests before provider-specific translation. A root policy applies to all requests, and a route policy can replace it for the Fable, Opus, Sonnet, or Haiku Claude tier.

Reasoning preferences

ReasoningPreference defines the shared values off, client, low, medium, high, xhigh, and max. inherit is available only for route and fallback settings. The root policy must choose a concrete value, so the system always has a defined starting policy.

The client value keeps the effort choice from the incoming client request. Other values express a fixed user choice. Each provider then maps only the controls that its API supports, so the same setting can have different provider-level effects. Custom providers add an API format and reasoning format that define how those controls are sent to the custom endpoint.

References: src/…/reasoning.py• L1-25 src/…/model_refs.py• L24-31 src/…/custom_providers.py• L18-30 src/…/custom_providers.py• L88-99 src/…/settings.py• L601-620 src/…/reasoning.py• L1-29 src/…/manifest.py• L18-33 src/…/manifest.py• L138-181

Route policy selection

Model routing checks a Claude model name for a known tier. It uses that tier's model override when present and otherwise uses the default model. It then applies the tier reasoning override when it is not inherit; otherwise it uses the root policy.

Direct provider/model requests bypass tier name mapping and use the named provider and model. Gateway model IDs can also force reasoning off. The resulting policy travels with the routed request before the selected provider receives it. Fallback entries can provide a separate reasoning choice for their own attempt.

References: src/…/routing.py• L21-26 src/…/routing.py• L67-108 src/…/routing.py• L138-180 src/…/routing.py• L190-214

Administrative configuration

The Admin surface is a local control plane for viewing, checking, and storing configuration. It presents the same settings contract used by the runtime, rather than maintaining a separate set of rules.

Admin settings view

The Admin manifest groups fields into provider, model routing, reasoning, runtime, messaging, voice, web tool, diagnostics, and smoke-test sections. Provider fields are generated from the provider catalog, while settings-backed fields use the same setting aliases as environment loading. Shared credentials appear once with their related provider IDs, and provider-specific account or project fields fill the gaps that are not credentials. Each field describes its input type, default behavior, secret status, allowed options, and whether a change needs a restart or a new session.

The settings response includes the effective value source and provider status. Secret values are masked, while API key fields expose only signed row references for later edits. Values supplied by the process environment are locked because the Admin file cannot safely override the live process. Provider status is derived from local settings and catalog metadata; connected-account entries report account state without treating them as API-key fields. The response also lists custom providers and reports whether their shared setting is process-owned and therefore read-only.

References: src/…/provider_manifest.py• L356-402 src/…/provider_manifest.py• L405-504 src/…/manifest.py• L37-80 src/…/manifest.py• L83-205 src/…/manifest.py• L568-609 src/…/values.py• L19-93 src/…/values.py• L96-173 src/…/specs.py• L23-78 src/…/status.py• L15-89

Admin update flow

An Admin update is a partial set of field values or one custom-provider mutation. The system merges it with the sparse managed state, ignores fields owned by the process, preserves masked secrets, validates the prospective complete settings value, and returns a masked preview before it writes anything.

Credential edits use signed revisions of the current ordered key list. The Admin client submits retain references or new values, and a changed revision stops the update so the editor cannot overwrite another credential change. Custom-provider edits use generated IDs, reject duplicate display names, and cannot remove a provider that saved model routes still use.

When the update is valid, the system writes the managed file atomically and clears the settings cache. Invalid proxy values, invalid custom-provider edits, and invalid setting combinations stop the update before the write. Changes that affect server binding or authentication can require a restart. Changes that affect messaging or an active voice credential can remain pending until the related runtime session is recreated. The runtime can request an automatic restart when a restart callback exists.

sequenceDiagram
    participant U as Admin UI
    participant A as Local Admin API
    participant V as Settings validation
    participant P as Managed config
    participant R as Runtime
    U->>A: Submit partial values or provider mutation
    A->>V: Build and validate prospective settings
    V-->>U: Masked preview or errors
    U->>A: Apply valid values
    A->>P: Atomic write with expected snapshot
    A->>R: Clear cache and refresh runtime state
    R-->>U: Applied result and pending restart fields

The Admin routes accept requests only from the local machine and mark Admin responses as non-cacheable. This limits the configuration surface to local administration and reduces the chance that a browser retains settings or status data.

References: src/…/credentials.py• L46-137 src/…/persistence.py• L41-147 src/…/persistence.py• L150-265 src/…/custom_providers.py• L25-102 src/…/validation.py• L11-40 src/…/values.py• L45-126 src/…/admin_routes.py• L56-85 src/…/admin_routes.py• L108-132 src/…/application.py• L177-212 src/…/application.py• L319-338 src/…/admin_cache.py• L7-49

Change checklist

When these files or sections are changed, remember to consider these:

  • Keep every new Settings field aligned with its environment alias, recognized-key set, Admin manifest entry, and source reporting.
  • Keep Settings snapshots immutable after validation. Route configuration changes through validated replacement so existing provider generations do not observe in-place mutation.
  • Keep provider catalog credentials, required settings, endpoint defaults, proxy fields, configuration_attrs(), catalog order, and Admin provider status in agreement. Shared credentials and provider-specific account or project fields must produce the intended Admin fields.
  • Keep ordered API-key normalization, first-key runtime selection, signed credential revisions, secret masking, and Admin retain-row behavior in agreement.
  • Keep custom-provider encoding, settings decoding, generated IDs, unique display names, model-reference validation, and Admin mutation rules in agreement. A provider must not be removable while a saved model route still uses it.
  • When renaming an environment key, add a migration and define how old values map to the new value. Do not remove the old key from recognition until existing managed files can be read safely.
  • Keep model reference validation, fallback decoding and key selection, retired-provider repair, model discovery, and route selection aligned on the same provider IDs and provider/model format.
  • Keep shared defaults in constants.py aligned with the settings model and the provider or protocol code that consumes them.
  • Mark settings that need a new process or session in the Admin manifest so an applied value is not reported as active when the current runtime still owns the old value.
  • Keep sparse Admin updates from overwriting process-owned fields or masked secrets. Check proxy values before the atomic write.
  • Keep the custom-provider setting process-owned as a whole when FCC_CUSTOM_PROVIDERS comes from the process environment. Do not allow a partial Admin mutation to write around that lock.
  • Keep displayed server URLs consistent with the bind-host rule. Wildcard and IPv6 hosts need browser-safe forms.
  • Keep secret-field masking, signed credential projections, and non-cacheable Admin responses in place when adding a credential or sensitive status value.
  • Keep new persistent state under the shared user configuration root and give its file or directory a dedicated path helper. If multiple processes can update it, define its lock path with the state path.
  • Keep catalog-derived provider fields deduplicated for shared credentials and apply presentation overrides only to Admin metadata. Do not create a second provider identity in the manifest.
  • Keep catalog-derived smoke-test fields aligned with provider IDs and display names so new providers appear in the correct advanced Admin section.

Important failure modes

TriggerConsequenceGuard
Managed configuration has an unsupported schema versionSettings loading stops instead of risking an unreadable or altered fileMigration checks the schema before writing
Two processes migrate or commit the managed file at the same timeOne process could otherwise overwrite a newer settings stateThe managed store uses a cross-process lock and rechecks the file before commit
A published Settings snapshot is mutated in placeProvider generations or model-catalog snapshots could observe changed values without validationSettings is frozen and changes use a new validated snapshot
A model value has no supported provider prefix or has duplicate fallbacksValidation rejects the configuration before routing can select an invalid targetSettings validates model references and fallback uniqueness
A fallback value is not a valid compact list or JSON arrayThe model settings cannot be decoded into an ordered fallback policyFallback parsing accepts only supported input forms and validates each entry
A retired provider remains in a model override or fallbackRouting can target a provider that the catalog no longer supportsModel normalization repairs retired references during migration and composition
WHISPER_DEVICE=nvidia_nim has no NVIDIA NIM key while voice notes are enabledThe settings snapshot is invalid and voice startup cannot proceedCross-field settings validation requires the key
A process environment value conflicts with an Admin updateThe process value remains effective and the Admin field is read-onlySource tracking marks process-owned fields as locked
A credential revision is stale when an Admin editor submits changesAnother editor's key changes could be silently overwrittenSigned credential revisions require the editor to reopen the current list
A masked secret is submitted as an Admin replacementThe stored secret remains unchanged instead of being replaced by the maskSparse update handling treats the mask as a retain instruction
A managed provider proxy has an invalid URLThe update is rejected before persistence, or startup repair removes the unmanaged invalid valueProxy validation runs before commit and repair uses the config lock
A shared credential or provider-specific setup field is mapped to the wrong providerAdmin status can show a provider as ready or missing for the wrong reasonCatalog metadata and manifest generation keep provider IDs and required settings together
A custom provider is deleted while a model override or fallback still names itA later settings load rejects the saved model referenceCustom-provider deletion checks all model settings before encoding the new provider list
A custom-provider mutation changes an ID or creates a duplicate display nameExisting model references or Admin provider selection can become ambiguousIDs are assigned by FCC and definitions require unique IDs and case-insensitive names
Custom providers are supplied by FCC_CUSTOM_PROVIDERS in the process environmentAdmin edits cannot change the effective provider setThe value source locks custom-provider mutations when process-owned
A server host or port change is applied without a restartThe managed file has the new value but the running listener still uses the old addressAdmin returns restart metadata and tracks pending fields
A local provider URL is empty or unreachableProvider checks report missing or offline instead of claiming readinessAdmin local status performs a bounded endpoint check
Admin state is served from a browser cacheOld values or provider status can remain visible after a changeAdmin paths use Cache-Control: no-store

Key files

FileWhy to read it
src/…/loader.pyShows source precedence, value ownership, validation, repair, conflict checks, and settings caching
src/…/settings.pyDefines the immutable typed settings contract and its key cross-field rules
src/…/constants.pyDefines shared model, context, timeout, and protocol defaults
src/…/env_migrations.pyExplains legacy import, key migration, schema state, credential normalization, model repair, and managed-file writes
src/…/paths.pyDefines the user configuration root, managed settings file, locks, and related persistent state paths
src/…/api_keys.pyDefines ordered credential normalization, duplicate checks, persistence, and runtime first-key selection
src/…/provider_catalog.pyDescribes provider IDs, access kinds, endpoint defaults, required settings, and provider order
src/…/custom_providers.pyDefines the stored custom-provider shape, compatible API and reasoning formats, and JSON encoding
src/…/custom_providers.pyDefines safe create, update, and delete rules for user-owned provider definitions
src/…/credentials.pyDefines signed, masked ordered-key edits and stale-editor conflict handling
src/…/provider_manifest.pyShows how provider setup fields follow the provider catalog, deduplicate shared credentials, and apply Admin presentation overrides
src/…/model_refs.pyDefines the shared provider/model reference shape, fallback values, and retired-provider repair
src/…/routing.pyShows how model tiers, fallbacks, and reasoning policies become a route
src/…/server_urls.pyDefines browser-safe local proxy and Admin URLs
src/…/manifest.pyDefines the Admin sections, setting metadata, reasoning options, and catalog-derived smoke-test fields
src/…/validation.pyBuilds prospective settings and turns validation errors into Admin responses
src/…/values.pyBuilds displayed values, source ownership, secret masks, credential projections, custom-provider data, and provider status
src/…/persistence.pyShows sparse update handling, validation, credential edits, custom-provider mutations, masked preview, atomic apply, and pending-change rules
src/…/logging_config.pyShows how diagnostic settings become structured JSON logs and how third-party logs are controlled
src/…/admin_routes.pyDefines the local-only Admin API and provider checks
src/…/application.pyShows how applied configuration reaches the running runtime