Save Claude setup once
Persistent gateway configuration, login troubleshooting and the 503 recovery path.
On this page
Overview
Use the gateway root, http://localhost:3000 on this installation. Claude sends /v1/messages; do not append /v1 to its base URL. Use a Conflux gateway key, never an upstream provider key. Checked with Claude Code 2.1.310 on 2026-11-01.
Keep the gateway running
The launcher connects to Conflux; it does not start a stopped server. Run npm run build then npm start from the Conflux checkout, or install the reviewed local user service with node scripts/install-local-runtime.mjs followed by node scripts/install-local-runtime.mjs --install. The service listens only on 127.0.0.1:3000, starts at user login and restarts on process failure.
For a source installation, npm run build creates .next and npm start serves it. The optional local service starts at user login and restarts on failure; boot/logout persistence needs a separately configured user lingering policy. Check systemctl --user status conflux-local. Preserve a known-working build and a matching database/key backup before upgrading. Never rebuild a directory while it is serving requests.
Automatic restart cannot keep a powered-off computer online. Provider failover requires another eligible account with capacity. When every account is exhausted, the gateway must wait for resets or report that no route is available.
The current launcher checks gateway reachability and key/model access before opening Claude. To update an existing recognized launcher without replacing its key or settings, run node scripts/install-claude-launcher.mjs --update-launcher. An unavailable gateway now fails once with a useful message. Route eligibility still needs the console's Route Inspector; the launcher check uses no generation.
See current repair evidence for real file/skill tasks, service recovery, UI screenshots and remaining limits.
Why the long command was needed every time
Bash export changes the current terminal and its child processes. It does not persist to a new terminal. --setting-sources "" deliberately skips saved user/project/local settings, including settings from another gateway. Setting ANTHROPIC_API_KEY and clearing ANTHROPIC_AUTH_TOKEN avoids conflicting auth. Those choices fixed login, but the one-session snippet did not install a launcher.
The current persistent launcher loads native user, project and local settings. It adds private, temporary connection settings so existing hooks, plugins, permission rules, skills and MCP servers remain available while Conflux auth/model mappings take precedence. Temporary settings are deleted on normal exit; the key never appears in command arguments. The current one-session snippet also loads local settings; it uses the same temporary connection override without saving a key.
claude auth login configures Anthropic login; it is not how a Conflux gateway key is connected. A custom-key approval prompt can still appear once. Managed Claude policies remain applicable. Conflux aliases name free-provider pools, not actual Anthropic models; Anthropic does not support this model substitution.
Save it once
From the Conflux checkout, with Node 24 and the official Claude CLI installed:
read -rsp 'Conflux gateway key: ' conflux_gateway_key
printf '\n'
printf '%s' "$conflux_gateway_key" | node scripts/prepare-claude-launcher.mjs --base 'http://localhost:3000'
unset conflux_gateway_key
node scripts/install-claude-launcher.mjsPreparation creates a private .cache/claude-launcher bundle. Installation creates ~/.local/bin/claude-conflux and ~/.config/conflux/{claude.key,claude.settings.json} (or $XDG_CONFIG_HOME/conflux). Key/settings permissions are 0600; launcher 0700. The gateway key is saved locally in plaintext, readable by your OS account; settings themselves contain no key. Use a dedicated restricted key and revoke it in API Keys to disconnect. Preparation/installation refuse existing files rather than replacing an existing setup. Keep the ignored prepared bundle private too.
Every subsequent terminal/project:
~/.local/bin/claude-conflux
# If ~/.local/bin is already on PATH:
claude-conflux
# Override the launcher's low-effort default when needed:
claude-conflux --effort highThe launcher reads the saved key, clears conflicting auth/provider environment variables, uses the explicit Conflux settings, maps Opus/Sonnet/Haiku/background aliases and defaults to acceptEdits. Read, Write and Edit work for ordinary project files; Bash and protected configuration paths still follow Claude permissions. Use --permission-mode manual or --permission-mode plan explicitly when wanted. The launcher uses eager tool schemas (ENABLE_TOOL_SEARCH=false) because the translated protocol does not implement Anthropic server tool search/references. It does not change .bashrc, Claude's normal settings, subscriptions or project instructions. For diagnosis only, claude-conflux --bare also removes hooks/plugins/automatic CLAUDE.md loading; provide necessary project context explicitly when using bare mode.
Files and skill installation
Start a fresh session from the project you want to edit:
cd /path/to/your/project
claude-conflux --conflux-doctor
claude-confluxAsk Claude to create a file, read it back, edit it and run a test. Verify the real files and tool results. A text answer claiming success does not establish execution. For print mode (-p), approve specific shell commands using --allowedTools, for example --allowedTools 'Bash(node --test *)'. Interactive permission prompts can approve protected .claude files; print mode can deny them automatically.
Install a local skill without depending on AI or a live gateway:
claude-conflux --conflux-install-skill /path/to/local-skill-folder
# Restart Claude, then type /the-skill-nameThe source is a directory containing SKILL.md and any supporting files. SKILL.md must begin with YAML name and description. The name uses lowercase letters, digits and hyphens. Installation copies into the current project's .claude/skills/<name> and refuses existing skills, symlinks, special files and bundles above 1000 entries / 20 MiB / 32 directory levels. It never fetches a remote skill or asks the model to interpret one during installation.
---
name: project-check
description: Check the project before finishing a change.
---
Read the project instructions. Run its relevant checks. Report actual results.Claude also discovers personal skills in ~/.claude/skills and supports its native plugin commands. The Conflux installer above is for local project skills. For remote marketplaces, use Claude's documented /plugin workflow and its permissions. Use /mcp to check configured MCP servers and /permissions to inspect denied tools. Custom --tools, plan mode, safe/restricted modes and managed policies can limit available actions. They are explicit client choices, not provider quota.
The current installed-client synthetic test verified Write → Read → Edit → test, local skill installation via an approved Bash command, restart/slash invocation, and a real local MCP round trip. It also verified that competing project auth/URL settings cannot redirect Conflux, and forced first-provider401 failover. These checks prove client/protocol behavior, not real free-model quality or capacity. See repair evidence.
Login success followed by 503
A greeting that succeeds proves authentication for that request. 503 means no usable route completed the next request, not a need to log in again. Claude may make separate Sonnet and Haiku/background requests. Inspect every tier used by that session, with Tools checked; add Vision only when the request uses images.
Open Usage Logs and the receipt. Read actual hops and route skips separately:
- 429 / exhausted observation: wait for the provider's reset; do not clear it.
- 413 request too large: the prompt can exceed a TPM cap even at low output tokens.
- NVIDIA timeout: queued inference/prefill can use the entire 30-second wait.
- Gemini 404: account/model access is unresolved; a catalog success is insufficient.
- Tools/vision unverified: select a verified model; do not bypass the filter.
The exhausted-chain response includes x-should-retry: false and a request ID. The Anthropic SDK honors the header; some CLI-level retry loops may differ by version. Later user requests still evaluate restored capacity normally. This header stops wasteful immediate SDK retries; it cannot create free quota.
See chain recommendations, AWS deployment and the verification report. A short tool round trip is not proof of full Claude default-tool fidelity or natural three-account exhaustion.
Official references, accessed 2026-10-24:
Search, browsing and complex tasks
Model answers about their own tools are not evidence. The free model served behind a Conflux alias can claim capabilities it does not have, or invent a sandbox restriction. Available tools come from the actual client configuration and must return a real result before their use is claimed.
Conflux does not implement Anthropic's hosted web-search service, server tools or remote compaction. Receiving a WebSearch-like name in a prompt does not provide a search backend. The gateway translates requests; it does not open a browser or run client tools. Local Bash, Read, Write and Edit tools execute in Claude Code. For search, use a configured local/MCP search tool with an actual backend. For interactive browsing, connect a browser MCP/tool such as an appropriately configured Playwright server, and grant its permissions. No browser/search MCP is installed by this repair, and compatibility needs a real test with your provider.
There is no blanket rule that a sandbox forbids browsing, JavaScript or all external APIs. Network permissions and installed tools determine access. Conflux's protocol limits remain separate. Complex coding tasks are possible through ordinary tool loops; quality, context and reliability depend on the selected model and available free quota. Subagent requests still consume quota and need working tier mappings.
Official references: