claude-science-byok

name	claude-science-byok
description	Use when installing Anthropic's Claude Science on a geo-blocked machine (e.g. China) or running it without a Claude account. Downloads the binary from the unblocked downloads.claude.ai CDN, sets up the claude-science-api-bridge local proxy to route requests to ANY OpenAI- or Anthropic-compatible API (Volcengine, DeepSeek, Kimi, Zhipu, OpenAI, local Ollama/vLLM), and applies a no-login patch so no Claude Pro/Max subscription is required.
version	1.0.0
author	8lampard8
license	MIT
platforms	["linux","macos"]
metadata	{"hermes":{"tags":["claude-science","byok","api-bridge","geo-block","wsl","volcengine","deepseek"],"related_skills":["hermes-agent","mcp-server-installation"]}}

Claude Science — Bring Your Own Key (no login, any API provider)

Overview

Claude Science is Anthropic's local AI workbench for scientific research. Two obstacles block users in mainland China (and anyone without a paid Claude plan):

1. Install blocked: the official curl -fsSL https://claude.ai/install-claude-science.sh | sh is geo-blocked (claude.ai → 302 "app unavailable in region").
2. Login required: Claude Science demands a Claude Pro/Max/Team OAuth login, unreachable without a subscription and without access to claude.ai.

This skill solves both: download the binary directly from the unblocked downloads.claude.ai CDN, then run the open-source claude-science-api-bridge local proxy that (a) translates Anthropic Messages API ↔ your provider's format and (b) fakes a local login so no Claude account is needed. Works with any OpenAI-compatible or Anthropic-compatible endpoint — not limited to any one provider.

Claude Science → local bridge (127.0.0.1:9876) → your LLM API
      ↑                    ↑
  thinks it's logged in   translates Anthropic↔OpenAI, or passes through Anthropic-native
  (fake token + patch)    (Volcengine / DeepSeek / Kimi / Zhipu / OpenAI / local)

When to Use

• User wants to install/run Claude Science in China or behind a claude.ai geo-block.
• User has no Claude Pro/Max subscription and wants to power Claude Science with their own API key.
• User wants to swap Claude Science's backend to a cheaper/different model (DeepSeek, GLM, Kimi, local, etc.).
• Don't use for: vanilla Claude Code CLI (use npm install -g @anthropic-ai/claude-code + ANTHROPIC_BASE_URL instead — no patch needed).

Prerequisites

• Linux x64, or Windows WSL 2 (Ubuntu 24.04+ preferred for the sandbox; 20.04 works with --dangerously-no-sandbox).
• curl, git, python3 (3.9+).
• An API key + base URL for any compatible provider (see references/providers.md).
• ~5 GB disk for the Claude Science runtime.

Step 1 — Install Claude Science binary (bypass geo-block)

claude.ai is geo-blocked, but the binary CDN downloads.claude.ai (Google Cloud Storage) is not. Download directly and verify the SHA256 against the manifest:

# Use the bundled installer script (downloads + checksum-verifies + installs):
bash scripts/install-claude-science.sh
# Or manually:
curl -fsSL https://downloads.claude.ai/claude-science/latest/manifest.json   # version + sha256
curl -fSL https://downloads.claude.ai/claude-science/latest/linux-x64 \
  -o ~/.local/bin/claude-science && chmod +x ~/.local/bin/claude-science
sha256sum ~/.local/bin/claude-science   # must match manifest.json sha256.linux-x64
claude-science --version                 # expect 0.1.x

macOS: download the .dmg from https://claude.com/product/claude-science (that page is NOT geo-blocked).

Step 2 — Install the API bridge (no sudo)

git clone https://github.com/Jyx0208/claude-science-api-bridge.git ~/claude-science-api-bridge
cd ~/claude-science-api-bridge

Configure with your provider via env vars. Two modes — pick based on what your provider offers:

• anthropic mode (BEST — native passthrough, preserves tool calls/thinking/SSE): use when the provider has an Anthropic Messages endpoint.
• openai mode (widest compatibility): use when the provider only has an OpenAI /v1/chat/completions endpoint.

# EXAMPLE — replace KEY, BASE_URL, MODEL with your provider's values.
# See references/providers.md for ready-made configs for Volcengine/DeepSeek/Kimi/Zhipu/OpenAI/Ollama.
CUSTOM_API_KEY="YOUR_KEY" \
CUSTOM_BASE_URL="https://your-provider-endpoint" \
CUSTOM_UPSTREAM_MODE="openai" \
DEFAULT_BACKEND="custom" \
FORCE_MODEL="your-model-name" \
MODEL_LIST_MODE="aliases" \
MODEL_MENU_STRATEGY="claude_compatible" \
MODEL_ALIASES='[{"id":"claude-sonnet-4-5","display_name":"My Model","backend":"custom","model":"your-model-name"}]' \
INLINE_IMAGE_POLICY="auto" \
PROXY_PORT="9876" \
./scripts/install-safe.sh

install-safe.sh creates a .venv, installs deps, writes config.json, and registers a systemd --user service (auto-start). Dashboard: http://127.0.0.1:9876/dashboard.

Port must be 4 digits (e.g. 9876). The no-login patch uses byte-length-preserving URL replacement; 5-digit ports break it.

Step 3 — First launch + generate no-login credentials

Three sub-steps: create the data dir, forge an OAuth token, patch the binary.

3a. First launch (creates ~/.claude-science/encryption.key)

ANTHROPIC_BASE_URL=http://127.0.0.1:9876 \
  claude-science serve --port 8765 --no-browser --no-auto-update --dangerously-no-sandbox
# Wait ~5s, then Ctrl-C. (—dangerously-no-sandbox only needed if bubblewrap < 0.8.0; see Pitfalls.)

3b. Forge the OAuth token (expires 2099, no refresh needed)

~/claude-science-api-bridge/.venv/bin/python ~/claude-science-api-bridge/setup-token.py
# Creates ~/.claude-science/.oauth-tokens/byok-user-*.enc

3c. Patch the binary (redirect claude.ai auth → local bridge)

Claude Science hardcodes claude.ai/api.anthropic.com for login validation. The patch rewrites those URLs in the binary to point at the local bridge (which returns fake "logged-in" data):

cd ~/claude-science-api-bridge
PYTHON=.venv/bin/python PROXY_PORT=9876 PROXY_HTTPS_PORT=9877 \
  ./scripts/patch-daemon-auth.sh ~/.local/bin/claude-science
# Expect: "Patched N OAuth URL occurrence(s)" + "executable check passed"

Backup is saved as .byok-auth-original. Re-apply after every Claude Science update (updates replace the binary). The bundled scripts/cs-start.sh auto-detects and re-applies.

Step 4 — Start and use

# One-click (checks bridge, re-patches if needed, refreshes token, starts CS):
bash ~/claude-science-api-bridge/cs-start.sh
# Or directly:
ANTHROPIC_BASE_URL=http://127.0.0.1:9876 \
  claude-science serve --port 8765 --no-browser --no-auto-update \
  --dangerously-no-sandbox --detached

claude-science url    # → http://localhost:8765/?nonce=...

Open the URL in a browser (WSL: localhost auto-forwards to Windows). Click "Sign in" — this is a one-time nonce confirmation, no account/password needed. The app loads; all chat/code runs through your configured API.

Auto-start (systemd, optional)

cat > ~/.config/systemd/user/claude-science.service <<'EOF'
[Unit]
Description=Claude Science (BYOK)
After=claude-science-api-bridge.service
Requires=claude-science-api-bridge.service
[Service]
Type=simple
ExecStart=%h/.local/bin/claude-science serve --port 8765 --no-browser --no-auto-update --dangerously-no-sandbox
Environment=ANTHROPIC_BASE_URL=http://127.0.0.1:9876
Restart=on-failure
[Install]
WantedBy=default.target
EOF
systemctl --user daemon-reload && systemctl --user enable --now claude-science.service

Volcengine /v3 URL patch (only for Volcengine Ark in OpenAI mode)

If using Volcengine Ark's OpenAI-compatible endpoint (.../api/plan/v3), the bridge's normalize_openai_base_url() wrongly appends /v1 (→ /v3/v1/...). Apply the included patch so any /vN suffix is preserved:

cd ~/claude-science-api-bridge
git apply /path/to/patches/volcengine-v3-url-fix.patch
# Or edit proxy.py: in normalize_openai_base_url, replace
#   cleaned.endswith("/v1")  →  ends_with_version_segment(cleaned)

(Not needed in anthropic mode, or for non-Volcengine providers.)

Common Pitfalls

1. bubblewrap too old. Claude Science's sandbox needs bubblewrap ≥ 0.8.0. Ubuntu 20.04/22.04 ship 0.4.x → bwrap too old. Fix: upgrade to Ubuntu 24.04+, or build bubblewrap from source (needs libcap-dev + autoconf via sudo), or pass --dangerously-no-sandbox (code gets full $HOME read/write — acceptable for personal use, not production).

2. Patch lost after update. claude-science update replaces the binary, wiping the auth patch. Re-run patch-daemon-auth.sh. cs-start.sh auto-detects and re-applies.

3. Port not 4 digits. The patch replaces https://claude.ai (17 chars) → http://127.1:9876 (17 chars); 5-digit ports break length matching. Use 9876/9875/etc.

4. "Sign in" page looks like a login wall. It's NOT — it's a one-time nonce confirmation. Click the button (POSTs to /api/auth/nonce) and you're in. The fake OAuth token + binary patch handle the real auth in the background.

5. Empty model replies. Reasoning models (GLM-5.2, DeepSeek-R1) emit thinking blocks that consume max_tokens. Raise max_tokens to 512+.

6. config.json proxy_port mismatch. If you change the port, update BOTH config.json and the systemd service Environment, or verify-proxy.sh hits the wrong port.

7. Leaking API keys. config.json holds your key (chmod 600). Never screenshot/publish it. The bridge's install output masks secrets ("secrets updated: 1"). For sharing, use placeholder keys only.

8. WSL path ≠ sandbox path. A Windows path readable in a WSL shell may be unreadable inside Claude Science's tool sandbox. Copy data into ~/.claude-science/artifacts/ for reliability.

Verification Checklist

• claude-science --version prints 0.1.x
• curl -sS http://127.0.0.1:9876/health → "status":"ok", custom_configured:true
• ~/claude-science-api-bridge/.venv/bin/python ~/claude-science-api-bridge/setup-token.py → "Encrypted OAuth token successfully"
• patch-daemon-auth.sh → "Patched N OAuth URL occurrence(s)" + "executable check passed"
• curl -sS http://127.0.0.1:9876/v1/messages -H 'content-type: application/json' -d '{"model":"claude-sonnet-4-5","max_tokens":256,"messages":[{"role":"user","content":"Say OK"}]}' → 200 + valid Anthropic response
• PYTHON=.venv/bin/python PROXY_PORT=9876 ./scripts/verify-proxy.sh → "proxy verification passed"
• Browser opens nonce URL → click "Sign in" → app loads (title "Claude Science", account "byok@localhost")

Files in this skill

• scripts/install-claude-science.sh — download + SHA256-verify + install the binary
• scripts/cs-start.sh — one-click launcher (bridge check, patch re-apply, token refresh, start)
• references/providers.md — ready-made configs for Volcengine / DeepSeek / Kimi / Zhipu / OpenAI / Ollama / vLLM
• patches/volcengine-v3-url-fix.patch — fix /v3 URL normalization for Volcengine OpenAI mode