Local Model Integrations
Relevant source files
The following files were used as context for generating this wiki page:
Local Model Integrations in CCS enable the execution of Large Language Models (LLMs) on local infrastructure, providing privacy, offline access, and cost-effective alternatives to cloud-based APIs. The system bridges standardized CLI interfaces, such as Claude Code and Codex, to local backends including Ollama and llama.cpp.
This integration is achieved through a combination of configuration presets, environment variable injection, and a local Anthropic-compatible proxy that routes requests to local OpenAI-compatible endpoints.
Sources: README.md:121-124, README.md:76-80
Architecture and Routing
CCS acts as a unified command surface that abstracts the differences between various local and remote runtimes. For local models, it typically utilizes a local proxy to transform Anthropic-style requests into formats accepted by local providers.
Local Proxy Flow
The local proxy supports profile:model selectors and scenario-based routing defined in proxy.routing. This allows users to force a specific local profile and upstream model during execution.
The diagram shows how requests from the CLI are intercepted by the local proxy and routed to specific local backends based on configuration.
Sources: README.md:83-93, src/config/loader/yaml-serializer.ts:70-76
Local Provider Configuration
Local models are defined within the CCS configuration as API profiles or CLIProxy variants. These profiles reference .settings.json files that contain the necessary environment variables for the local runtime.
Configuration Structure
Local providers are primarily managed through three sections in config.yaml:
- Profiles: Points to settings files for specific local endpoints.
- CLIProxy: Manages variants for local-model profiles.
- Global Env: Injects variables to disable telemetry and error reporting for third-party/local providers.
Sources: src/config/loader/yaml-serializer.ts:46-68, src/config/loader/yaml-serializer.ts:241-255
Core Parameters for Local Providers
| Parameter | Description | Source |
|---|---|---|
base_url | The local endpoint (e.g., http://localhost:11434/v1 for Ollama). | tests/unit/web-server/codex-dashboard-service.test.ts:88-91 |
supports_websockets | Boolean indicating if the local provider supports socket communication. | src/web-server/services/codex-dashboard-service.ts:515-517 |
experimental_bearer_token | Used for local providers requiring basic token authentication. | src/web-server/services/codex-dashboard-service.ts:518-520 |
wire_api | Set to "responses" for specific compatible CLI bridges like Codex. | src/web-server/services/codex-dashboard-service.ts:513 |
Local Runtimes
Ollama Integration
CCS supports Ollama as a privacy-focused local backend. It is typically launched via the ccs ollama command.
- Default Endpoint:
http://localhost:11434/v1 - Diagnostic Markers: CCS redacts local URLs in diagnostics to
[redacted:http]for consistency, but checks for the presence ofbase_url.
Sources: README.md:52, tests/unit/web-server/codex-dashboard-service.test.ts:88-91, src/web-server/services/codex-dashboard-service.ts:71-77
Codex Local Routing
The Codex integration allows for local model providers through a dedicated [model_providers] section in config.toml. This includes support for "OSS" (Open Source Software) providers.
The class diagram illustrates the relationship between the main Codex configuration and the definitions of local model providers.
Sources: src/web-server/services/codex-dashboard-service.ts:476-492, src/web-server/services/codex-dashboard-service.ts:77
Implementation Details
Diagnostic Logic
The system performs health checks on local model configurations, specifically warning if an active local provider is selected without a defined base_url.
// src/web-server/services/codex-dashboard-service.ts:684-690
if (activeProvider) {
if (!activeProvider.baseUrl) {
warnings.push(`Active model provider "${activeProvider.name}" is missing base_url.`);
}
if (!activeProvider.envKey && !activeProvider.requiresOpenaiAuth) {
warnings.push(`Active model provider "${activeProvider.name}" is missing env_key.`);
}
}
Sources: src/web-server/services/codex-dashboard-service.ts:684-690
Security and Telemetry
When using local models, CCS often injects global environment variables to ensure privacy. These include:
DISABLE_BUG_COMMAND: Disables upstream bug reporting.DISABLE_ERROR_REPORTING: Disables error telemetry to Anthropic.DISABLE_TELEMETRY: Disables usage tracking.
Sources: src/config/loader/yaml-serializer.ts:245-250
Summary
Local Model Integrations allow CCS users to transition between cloud-based Anthropic models and local alternatives like Ollama or llama.cpp. By utilizing a local proxy and environment variable injection via .settings.json profiles, CCS provides a consistent developer experience across both private local hardware and public API providers.