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-and-runtime

Configuration and runtime composition

Free Claude Code turns saved settings and process state into one running server. The configuration layer validates access, model routes, limits, paths, and safety choices. The runtime layer uses that validated view to assemble the API, provider access, model catalog, code sessions, voice support, and optional messaging services.

Configuration model

src/…/settings.py defines the validated settings contract used by the application. It brings provider access, model routes, request limits, proxies, logging, server options, voice, messaging, and local web-tool policy into one typed view.

Settings use environment-style names such as MODEL and OPENROUTER_API_KEY. Empty optional values become absent. Model values use a complete provider/model-name form, and the provider prefix must be known to the built-in catalog or to the saved custom-provider set. The model choices include one default, route-specific overrides, and an ordered fallback list. The built-in default is nvidia_nim/nvidia/nemotron-3-ultra-550b-a55b.

The settings contract also joins related choices. Custom provider IDs and display names must be unique, and fallback entries cannot select an API key that is not configured. NVIDIA NIM voice transcription needs an NVIDIA NIM key. The voice device, messaging platform, reasoning policy, log level, and web URL schemes must use supported values. These checks keep invalid combinations out of runtime assembly.

Shared defaults keep the fallback model, model context allocation, provider retry count, HTTP connect timeout, and default output limit consistent across configuration and provider use.

API credentials are ordered lists even when a user supplies one key. Runtime resources use the first key, while the Admin boundary can preserve, replace, reorder, or remove rows without exposing secret values. A credential revision prevents an old Admin view from overwriting a newer key list.

The Admin boundary describes settings with typed field metadata. The manifest combines general settings with provider fields derived from the provider catalog. The metadata tells the Admin UI how to render a field and whether it is secret, advanced, nullable, session-sensitive, or restart-sensitive. The resulting view includes source, lock, readiness, and masked-value information without making network calls. See Configuration lifecycle for the update and persistence flow.

References: src/…/settings.py• L60-128 src/…/settings.py• L406-431 src/…/settings.py• L742-859 src/…/constants.py• L1-15 src/…/manifest.py• L37-80 src/…/manifest.py• L83-145 src/…/manifest.py• L538-567 src/…/api_keys.py• L9-60 src/…/credentials.py• L46-137 src/…/specs.py• L23-78 src/…/values.py• L96-173

Configuration sources

The loader combines defaults, the managed environment file, and the current process environment into a ManagedConfigSnapshot. The snapshot carries validated settings, the source of each effective value, and the raw managed and process values. This source view lets the Admin boundary show who owns a setting.

Process values normally take priority over managed values. The retained ANTHROPIC_AUTH_TOKEN is the deliberate exception because servers and separately launched clients share that token. Process-owned fields are read-only through managed persistence. The process-wide settings view is cached until a committed configuration update clears it.

Loading and writing use a cross-process lock. A partial Admin update changes the sparse managed view, validates the complete prospective settings, and then writes only settings that the managed source may own. Secret values stay masked in responses. A stale editor receives a configuration conflict instead of silently replacing a newer file.

Unknown keys can remain in the canonical file for preservation, but they do not become application settings. Recognized provider proxy values receive an additional repair step when their managed value is invalid and the process does not own the same key. Retired model references are normalized separately in both sources before the effective settings are validated, so this repair does not change source precedence.

References: src/…/loader.py• L33-59 src/…/loader.py• L60-148 src/…/loader.py• L151-205 src/…/persistence.py• L93-147 src/…/persistence.py• L150-265 src/…/errors.py• L1-5

Environment-file migration

The managed environment file is the canonical user configuration at ~/…/.env. On first use, migration imports recognized values from older user locations, an explicitly named legacy file, or a verified checkout file. It writes a sparse managed file with schema version 2.

Migration translates retired names and old value forms. It covers older Hugging Face credentials, boolean reasoning settings, earlier OpenCode names and model prefixes, ordered API-key values, and custom-provider credential shapes. New names take precedence over old names. Empty recognized values are removed, while unknown settings are preserved for later handling. It also replaces the retired NVIDIA model endpoint with the current default in direct model settings and fallback entries.

The managed file is written atomically with restrictive permissions on non-Windows systems. A schema version that this release does not support stops loading instead of being silently rewritten. Retired provider references are repaired during migration and during later settings preparation, so old model choices do not select removed providers. Existing schema-1 files also receive the current credential-list normalization before they move to schema 2.

References: src/…/env_migrations.py• L26-39 src/…/env_migrations.py• L138-188 src/…/env_migrations.py• L191-262 src/…/env_migrations.py• L265-305 src/…/env_migrations.py• L317-344 src/…/model_refs.py• L20-135

Filesystem paths

The path layer gives user state one stable home. This keeps configuration and long-lived runtime data independent from the current working directory.

ResourceDefault locationPurpose
Managed settings~/…/.envCanonical user settings
Configuration lock~/…/config.lockCoordinates configuration migration and writes
Shared FCC database~/.fcc/fcc.dbShared application data
Server log~/…/server.logStructured server events
Messaging state~/.fcc/agent_workspacePersistent messaging session data
Launcher temporary files~/.fcc/tmp/launchersPrivate native launcher state
Code session database~/.fcc/code/code.dbLocal code session records
Code session lock~/…/code.lockCoordinates code session access
Codex model catalog~/…/codex-model-catalog.jsonModel inventory for Codex clients
OpenAI auth~/…/openai.jsonPrivate connected-account credentials
OpenAI auth lock~/…/openai.lockCoordinates connected-account access
GitHub Copilot auth~/…/github_copilot.jsonFCC connection state for Copilot

HOST and PORT control the server bind address. Human-facing local URLs replace wildcard bind hosts with a loopback host. Clients use one canonical local proxy root and a /v1 API form. See API gateway for the client-facing boundary.

References: src/…/paths.py• L25-110 src/…/server_urls.py• L8-55 src/…/settings.py• L742-756

Logging

Logging sends structured JSON lines to the configured server log. Standard-library records enter the same stream, so the server and its libraries share one log view. The file sink rotates at a fixed size and retains a small number of older files.

The normal policy favors metadata over content. Separate settings can enable raw API payloads, raw stream events, messaging content, CLI diagnostics, API error traces, and messaging error details when diagnosis needs them. Third-party loggers stay at warning level unless verbose third-party logging is enabled.

Repeated setup with the same path, level, and verbosity is safe. A path or level change replaces only the file sink. This lets runtime changes adjust logging without rebuilding the application graph.

References: src/…/logging_config.py• L1-7 src/…/logging_config.py• L62-80 src/…/logging_config.py• L83-137 src/…/settings.py• L667-697 src/…/manifest.py• L413-492

Provider catalog

The provider catalog is the neutral registry of supported model services. Each descriptor defines a stable provider ID, user-facing name, authentication kind, credential source, endpoint policy, proxy choice, required settings, and local or remote status. Custom providers add user-defined IDs without changing the built-in catalog.

The catalog separates provider metadata from provider adapters. Many entries use shared OpenAI-compatible behavior. Dedicated adapters and connected-account providers use their own runtime paths. Local providers use fixed local credentials and default endpoints. Catalog order also controls provider lists and model-related error messages.

Provider readiness depends on all settings that define access. A provider that needs a key and an account or project value is incomplete until both are present. Fixed catalog endpoints are not editable settings. Providers with account- or region-specific endpoints keep a base URL setting.

The Admin provider manifest is generated from the same catalog. It creates fields for credentials, base URLs, and proxies, then applies only presentation overrides for labels or special restart behavior. This keeps provider status, editable fields, validation, and runtime discovery on one vocabulary. The catalog keeps ChatGPT connected-account access separate from the OpenAI Platform API-key service. See Provider runtime and discovery for the provider-facing runtime boundary.

References: src/…/provider_catalog.py• L108-143 src/…/provider_catalog.py• L146-230 src/…/provider_catalog.py• L375-413 src/…/provider_catalog.py• L781-824 src/…/provider_manifest.py• L357-505 src/…/values.py• L143-172

Custom providers

Custom providers let an operator add an API endpoint to the same model-routing system as built-in providers. A definition has an FCC-assigned ID, a unique display name, an HTTP or HTTPS base URL, an API format, optional ordered credentials, reasoning format choices, and model IDs.

The definition rejects URLs that contain credentials, queries, or fragments. It removes blank and duplicate model IDs. It accepts the earlier single api_key shape only as an input migration to the ordered api_keys form. Reasoning choices must fit the selected API format, and reasoning history is available only for Chat Completions.

Admin mutations assign IDs, enforce unique names, keep credentials in the ordered-key editor, and block deletion while any active model route still uses the provider. Custom-provider state can be owned by the process environment. In that case the Admin view exposes it as locked. Otherwise, keyed changes are merged into a new prospective configuration and validated with the rest of the settings.

References: src/…/custom_providers.py• L18-30 src/…/custom_providers.py• L33-104 src/…/custom_providers.py• L106-133 src/…/custom_providers.py• L18-102 src/…/persistence.py• L189-231 src/…/values.py• L156-172

Model catalog

Model settings use complete provider/model references so routing never depends on a model name alone. The system collects the default, route-specific choices, and ordered fallbacks into a unique set. That set tells runtime discovery which providers and models matter to the current configuration.

The provider vocabulary includes built-in IDs and saved custom-provider IDs. It also keeps openai for the ChatGPT connected account separate from openai_api for the OpenAI Platform API. Retired provider references such as github_models/... are removed during normalization, while the retired NVIDIA model endpoint is replaced with the current default. These repairs do not change source precedence.

The provider manager caches model metadata for usable providers. It starts discovery for providers used by configured routes and model lists, then refreshes missing or changed provider lists in the background. The current model view is also published as a stable Codex catalog file when startup has at least one routable model.

References: src/…/model_refs.py• L20-35 src/…/model_refs.py• L95-135 src/…/model_refs.py• L177-213 src/…/custom_providers.py• L83-111 src/…/custom_providers.py• L45-73 src/…/values.py• L154-172 src/…/provider_manager.py• L316-392

Runtime diagnostics

Runtime diagnostics provide a shareable local snapshot without starting the application or changing its state. The report separates safe runtime, routing, reasoning, web-tool, provider, integration, harness, and model-discovery information so a support check can show system readiness without exposing secrets.

Provider rows show whether access is configured and whether the provider is referenced by current routing. URL values become origin summaries, while credentials and other sensitive settings remain excluded. If a local server is already running, diagnostics can read its safe provider discovery status; they do not refresh providers as part of the report.

The report records missing, invalid, or unavailable configuration as named errors. It also records integration and connected-account availability and probes supported command-line harnesses with bounded checks. These results describe the local state without changing the running server.

References: src/…/diagnostics.py• L38-146 src/…/diagnostics.py• L169-210 src/…/diagnostics.py• L301-338 src/…/diagnostics.py• L341-400

Bootstrap composition

The production bootstrap is the composition root for one server process. It configures logging, creates connected-account support, wires provider construction, creates the provider manager, selects voice transcription, creates code-session support, and exposes the resulting services through the API.

The application runtime owns process-lifetime resources. Startup initializes configuration, starts model refresh, connects catalog-change notifications, removes retired chat state, starts integration and code-session work, and starts messaging when the selected platform is configured. Shutdown first stops new work, then waits for background tasks and closes messaging, code sessions, the provider manager, and connected accounts.

The ASGI wrapper keeps HTTP handling in the API application and maps server lifespan events to the runtime. A startup failure reports a safe error to the server host and closes resources that were already created. Admin changes are serialized, credentials are checked before commit, and a provider replacement is published when the change can take effect without a restart.

This diagram shows how validated process state becomes the service graph that handles API traffic.

flowchart TD
    A[Process and managed settings] --> B[Resolve and validate settings]
    B --> C[Configure structured logging]
    B --> D[Build provider manager]
    D --> E[Create provider runtime on demand]
    B --> F[Select voice transcription]
    D --> G[Warm and refresh model catalog]
    B --> H[Create code-session and optional messaging services]
    C --> I[Create API services]
    D --> I
    F --> I
    H --> I
    I --> J[ASGI application]
    J --> K[Startup and shutdown lifecycle]

Provider runtimes are grouped into generations. A configuration update builds and validates a replacement before publishing it. Requests keep a lease on the generation they started with, so an old provider set closes only after those requests finish. See Runtime startup and provider management for provider generations and lifecycle ownership.

References: src/…/bootstrap.py• L40-95 src/…/application.py• L100-215 src/…/application.py• L226-265 src/…/application.py• L270-371 src/…/provider_manager.py• L216-221 src/…/provider_manager.py• L551-609 src/…/asgi.py• L9-63

Change checklist

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

  • Keep each provider descriptor aligned with its credential, endpoint, proxy, required settings, Admin field, status calculation, and runtime construction owner.
  • Keep custom-provider fields aligned across JSON encoding, settings validation, Admin masking, keyed mutations, model-reference validation, and provider construction.
  • Keep every accepted provider/model prefix aligned with the provider catalog, custom-provider IDs, retired-reference repair, migration recognition, and model discovery.
  • Keep settings aliases, migration recognition, secret masking, typed Admin metadata, and Admin value handling aligned when a setting is added or renamed.
  • Keep provider proxy validation and managed-file repair aligned with process-variable precedence.
  • Keep schema version checks and atomic writes aligned between initialization, reads, and Admin commits.
  • Keep local bind URLs, browser URLs, client proxy roots, and /v1 normalization aligned when host or port behavior changes.
  • Keep each process-lifetime resource in both the bootstrap ownership graph and the ordered shutdown path.
  • Keep model catalog publication valid when provider availability or connected-account state changes.
  • Keep log controls aligned with the safe-error paths that decide whether content or exception details are exposed.
  • Keep diagnostics field groups, exclusions, URL summaries, and live-server status reads aligned with the settings and provider catalog.
  • Keep separate authentication paths distinct when one product has both a connected account and an API-key provider.

Important failure modes

TriggerConsequenceGuard
A model setting uses an unknown provider prefixSettings validation rejects the configuration before routing startsValidate references against built-in and custom provider IDs
A custom provider has an unsafe URL, unsupported format, or invalid reasoning choiceThe provider cannot enter the active model vocabularyValidate the full definition before saving it
A custom provider is removed while a model route uses its IDA saved route would point to a missing providerReject removal until the model settings change
A provider lacks a required key, project value, account value, or endpointProvider creation or model discovery cannot use that providerDerive required settings from catalog metadata and check them before use
Voice notes select NVIDIA NIM without an NVIDIA NIM keySettings validation rejects the configurationRequire the key when voice notes and the NVIDIA NIM device are enabled
A managed file has an unsupported schema versionConfiguration loading stops instead of rewriting unknown dataAccept only the current managed schema
A stale Admin editor submits an old key list or snapshotA newer credential or setting can be overwrittenRequire a credential revision and compare the expected managed snapshot
A retired provider reference or model endpoint remains in settingsRouting can select an unavailable provider or modelRemove retired provider references and replace the retired model endpoint during migration and source composition
Startup cannot build or warm a required resourceASGI startup fails and partial resources must be cleaned upLet the application runtime own startup failure cleanup
A provider generation is replaced during a requestClosing the old generation can break in-flight workDrain request leases before closing retired generations
A diagnostic report reads an unavailable or invalid local stateThe report marks that section unavailable instead of giving a false ready resultUse safe status values and record named report errors
Raw content or exception detail logging is enabled without a diagnosis needLogs can contain user content or provider dataKeep raw-content settings disabled by default

Key files

FileWhy to read it
src/…/settings.pyDefines the validated settings contract for the application
src/…/constants.pyDefines shared defaults used by settings and provider behavior
src/…/loader.pyShows source precedence, provenance, locking, proxy repair, and settings caching
src/…/env_migrations.pyExplains canonical env-file creation, legacy migration, key recognition, and atomic persistence
src/…/api_keys.pyDefines ordered secret credentials and runtime key selection
src/…/model_refs.pyDefines provider/model references and retired-reference repair
src/…/paths.pyDefines stable locations for user state and generated files
src/…/server_urls.pyDefines browser-facing local URLs and the canonical local proxy API root
src/…/custom_providers.pyDefines the saved custom endpoint contract and supported API formats
src/…/persistence.pyShows how Admin updates become validated sparse changes
src/…/manifest.pyDefines the Admin sections and general setting fields
src/…/provider_manifest.pyShows how editable provider settings follow the catalog
src/…/credentials.pyShows masked, version-bound credential edits
src/…/provider_catalog.pyDefines the supported provider and model-routing vocabulary
src/…/logging_config.pyDefines structured logging and third-party log handling
src/…/bootstrap.pyShows how the production service graph is assembled
src/…/application.pyOwns startup, shutdown, Admin changes, and optional services
src/…/provider_manager.pyCoordinates provider generations, leases, discovery, and model metadata
src/…/diagnostics.pyBuilds safe local configuration, integration, harness, and discovery reports
src/…/asgi.pyConnects ASGI lifespan events to runtime ownership