CC Switch Web: setup and provider-switching workflow
Use this workflow with Laliet/cc-switch-web, the web-enabled fork of farion1231/cc-switch. It helps configure the external application and verify a requested change. Installing this skill adds instructions for an AI assistant; it does not install the app, migrate credentials, or change any active provider.
Inputs
Identify the task: a new deployment, a provider change, an MCP change, or troubleshooting. Record the target application, operating system, server host, runtime user, current CC Switch Web version, and intended access method. Obtain configuration paths from the target host. Ask for a redacted provider URL, model identifier and relevant error when needed; credentials stay in the user's private account or local secret store.
The web console manages the server's files and processes. A browser on a laptop does not make that laptop's Claude Code, Codex or Gemini configuration available on a remote host. A container sees its own filesystem unless specific host directories are mounted. Establish that boundary before proposing a deployment or a file change.
Method
1. Inspect the existing installation
Check the repository and release being used; several independent projects share the CC Switch Web name. This workflow references Laliet's fork, reviewed at commit 324dfc384d195eebc3442966b73f97fa4919a458 and release v0.21.0. Do not apply another fork's ports, environment variables or executable names without checking that fork's documentation.
For an existing service, inspect its launch configuration, runtime HOME, data directory and config overrides. Do not start a second process on its port, replace a container, or switch to an unpinned image as a troubleshooting shortcut. Capture a backup before any configuration write, using the app's export facility and copies of the affected CLI files. Protect the backup because it may include credentials.
2. Choose a runtime
For a new Linux headless installation, compare the release's server binary with a source build or Docker. Select the correct architecture and check the release's platform requirements. Desktop installers are not interchangeable with the headless server. Review download checksums where supplied; never disable verification to make an install succeed.
The following is the source-build path for the reviewed revision. It requires Git, Node.js, pnpm, Rust, pkg-config and the platform's OpenSSL development dependencies. Run it in a new directory; if that directory exists, inspect it and preserve local changes.
git clone https://github.com/Laliet/cc-switch-web.git
cd cc-switch-web
git checkout 324dfc384d195eebc3442966b73f97fa4919a458
pnpm install --frozen-lockfile
pnpm build:web
cd src-tauri
cargo build --release --no-default-features --features web-server --example server
HOST=127.0.0.1 PORT=3000 ./target/release/examples/server
This launch example is for a POSIX shell. On Windows use a supported runtime or set equivalent environment variables in the shell being used. If the selected port is occupied, choose an available port and use it consistently in browser URLs, tunnels and proxy configuration.
For Docker, inspect the selected image rather than copying a data mount from an unrelated guide. At the reviewed revision the release image runs as ccswitch with HOME /home/ccswitch; its application state directory is /home/ccswitch/.cc-switch. One upstream guide shows a conflicting /root/.cc-switch mount. Verify the actual image user and paths, mount persistent storage at the effective path, and check ownership. A state volume alone does not mount the host's CLI configurations.
List the exact host configuration directories the container needs. Mount only those directories and distinguish read-only inspection from requested write access. Never mount the entire host filesystem to solve a missing-path error. Check authentication and non-loopback binding requirements before publishing a container port. Preserve volumes when replacing a container and record the selected tag or digest.
3. Verify access and capabilities
For the reviewed native server, HOST defaults to 127.0.0.1 and PORT to 3000. Keep local access on loopback. For a remote host, use an SSH tunnel or a configured HTTPS reverse proxy. A tunnel example, with an actual SSH destination substituted for USER@SERVER, is:
ssh -N -L 3000:127.0.0.1:3000 USER@SERVER
The reviewed app uses Basic Auth. Its initial username is admin; the generated password is stored under the runtime user's ~/.cc-switch/web_password. Let the user read it privately. Do not paste passwords or API keys into chat, shell arguments, screenshots or shared logs. Do not bypass authentication or expose Basic Auth over public plain HTTP.
Check that an unauthenticated API request is denied and that an authenticated GET /api/capabilities returns the runtime's supported features. When curl is available, this command prompts for the password rather than including it in the command line:
curl --user admin http://127.0.0.1:3000/api/capabilities
In Windows PowerShell use curl.exe when curl resolves to the PowerShell alias. Never add an option that disables certificate validation. For manual API writes, follow the reviewed server's CSRF-token flow; use the web UI when possible. CORS settings control browser origins and do not replace authentication.
4. Change one provider or integration
Read the target application's capability flags before offering controls. Claude Code, Codex and Gemini do not have the same capability set as OpenClaw or OMO. For the reviewed version, OpenClaw local routing, MCP, prompts, skills and usage are unsupported; OMO does not provide local proxy takeover. Native dialogs and tray controls belong to desktop mode. Treat an unsupported capability as a boundary, not an installation failure to work around.
Record the active provider and the affected configuration paths. Create or edit a provider profile with the intended endpoint, model and credential reference. Confirm the provider supports the target tool's required protocol; an OpenAI-compatible endpoint is not proof that it works with every client. Change only the requested profile or setting. Preserve unrelated MCP servers, prompts, model options and authentication configuration.
Use the app's normal UI flow to apply the switch. Compare the affected files with the backup, redacting values in any report. Check that unrelated settings remain present. If the task includes a live provider test, send a minimal request with the intended client and explain that the provider may charge for it. UI selection, a stream health check and a successful client request are separate observations; report which actually passed.
5. Verify persistence and rollback
Check the active provider in the target CLI, inspect requested MCP settings, and confirm configuration is stored under the expected runtime user. Restart only the service involved in the requested setup when needed to test persistence. Preserve the data volume and recheck authentication after restart.
If the change fails, restore the previous provider and the relevant configuration from the backup. Resolve current file changes or version conflicts before restoring an older snapshot. Do not delete sessions, remove containers with their volumes, reset the entire app or overwrite a newer file as an automatic recovery step.
Output
Report the repository and revision, target host, runtime user, application version, access URL, configuration paths, and backup location. List the requested changes and the checks actually performed: authentication, capabilities, configuration preservation, persistence, and any live client test. Redact secrets and omit credentials from URLs.
Provide a rollback action and identify what remains untested. A source review or successful dashboard load does not establish that every provider, MCP integration or runtime feature works. If the user asked only for guidance, return a plan rather than changing their machine.
Source and scope
This original Thrive skill references Laliet/cc-switch-web at the reviewed revision, its README, Dockerfiles and Web Server Guide, reviewed 15 October 2026. The external application is MIT-licensed and credits Jason Young's farion1231/cc-switch. This skill is independently maintained and does not redistribute the application or certify its security. Check the selected release's current documentation before deployment.
