Web Server APIs
Relevant source files
The following files were used as context for generating this wiki page:
- src/web-server/routes/index.ts
- src/web-server/routes/cliproxy-auth-routes.ts
- src/web-server/index.ts
- src/web-server/routes/bar-routes.ts
- src/web-server/routes/codex-routes.ts
- src/web-server/routes/claude-extension-routes.ts
- src/web-server/shared-routes.ts
- src/web-server/services/codex-dashboard-service.ts
The CCS Web Server provides a comprehensive suite of RESTful APIs designed to manage AI provider profiles, authentication states, local configurations, and dashboard telemetry. These APIs serve as the bridge between the React-based dashboard UI and the underlying CLI and file system, enabling seamless management of Claude Code, Codex, and other supported runtimes.
Sources: AGENTS.md:10-15, src/web-server/index.ts
Core API Architecture
The web server is built using Express and organized into specialized routers. Each router handles a specific domain of the CCS ecosystem, such as authentication, telemetry (Bar), or provider-specific configurations (Codex, Claude).
The diagram shows how the Express server dispatches requests from the UI to specialized route handlers and their respective data targets.
Sources: src/web-server/index.ts, src/web-server/routes/index.ts
Specialized API Modules
Bar Service (Telemetry & Monitoring)
The Bar API provides real-time data for the dashboard and macOS menu bar (CCS Bar). It aggregates account health, quota usage, and daily costs across multiple providers.
| Endpoint | Method | Description |
|---|---|---|
/api/bar/summary | GET | Returns a flat array of account statuses, including health, quota, and cost. |
/api/bar/refresh | POST | Triggers a force-refresh of cached account telemetry. |
The /summary endpoint supports a refresh=true query parameter, which invalidates the local cache and performs a live fetch from providers, subject to a 15-second debounce window to prevent rate-limiting.
Sources: tests/unit/web-server/bar-routes.test.ts:40-100, src/web-server/routes/bar-routes.ts
Codex Configuration & Profiles
The Codex API manages the config.toml file and user profiles for the Codex runtime. It supports structured patching to modify model settings, feature flags, and project trust levels.
This flow illustrates the structured patching mechanism used to safely update Codex configuration files.
Sources: src/web-server/routes/codex-routes.ts, tests/unit/web-server/codex-dashboard-service.test.ts:250-300
Shared Resources API
Shared routes manage common AI assets like skills, agents, and custom commands. These resources are typically located in ~/.ccs/shared and linked to specific runtimes.
- Skills: Lists and retrieves markdown-based skill definitions from symlinked directories.
- Agents: Manages agent prompts and metadata.
- Plugins: Interacts with the shared plugin registry (
installed_plugins.json). - Settings: Provides access to shared environment variables and permissions in
settings.json.
Sources: tests/unit/web-server/shared-routes.test.ts:100-250, src/web-server/shared-routes.ts
Claude Extension Bindings
The Claude Extension API facilitates integration with IDEs like VS Code, Cursor, and Windsurf. It manages "bindings" that synchronize environment variables between CCS profiles and IDE settings.
| Parameter | Type | Description |
|---|---|---|
profile | string | The CCS profile name to bind (e.g., 'glm', 'work'). |
host | string | The target IDE ('vscode', 'cursor', 'windsurf'). |
ideSettingsPath | string | File system path to the IDE's settings.json. |
Sources: tests/unit/web-server/claude-extension-routes.test.ts:120-180, src/web-server/routes/claude-extension-routes.ts
Security and Access Control
The Web Server implements several security layers to protect sensitive configuration data:
- Localhost Guard: By default, APIs are restricted to loopback access unless explicit dashboard authentication is enabled. This prevents unauthorized network access to configuration files.
- Redaction: Diagnostic and telemetry summaries redact sensitive fields such as
base_url(protocol only),env_key(existence check), and bearer tokens. - Conflict Detection: Configuration writes often require an
expectedMtime. If the file was modified on disk since the last read, the API returns a409 Conflict.
Sources: tests/integration/web-server/codex-profiles-endpoint.test.ts:180-210, tests/unit/web-server/codex-dashboard-service.test.ts:80-100, tests/unit/web-server/codex-routes.test.ts:80-100
Conclusion
The Web Server APIs provide a robust and secure management layer for the CCS ecosystem. By abstracting file system operations and provider-specific protocols into standardized REST endpoints, CCS enables a unified control surface for diverse AI runtimes while maintaining strict data integrity and local-first security principles.