AI-Cognitive-Leap/agnes-the-ai-analyst
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs(marketplace): document two-step fallback for marketplace registration

Browse source 
The 'Git channel' block previously showed only the direct '/plugin
marketplace add https://x:$AGNES_PAT@…' path. That path fails on
macOS/Windows against a private-CA Agnes instance because Bun-compiled
'claude' ignores the OS trust store and CA env vars on the marketplace
HTTPS path (see the existing rationale in app/web/setup_instructions.py).

Document the two-step fallback explicitly:

  git clone https://x:$AGNES_PAT@agnes.example.com/marketplace.git/ \
    ~/agnes-marketplace
  claude plugin marketplace add ~/agnes-marketplace

System 'git' honors GIT_SSL_CAINFO + the OS trust store, so the clone
succeeds where direct add fails; pointing Claude Code at the local clone
then sidesteps the Bun TLS path entirely. The dashboard-served setup
payload already branches between the two automatically based on
platform; the docs now match that behavior for manual flows.

Also note the optional 'remote set-url' hardening to strip the PAT from
the cloned repo's origin (mirrors what the dashboard payload does).
This commit is contained in:
Vojtech Rysanek 2026-05-06 11:00:59 +04:00
parent f598b7e2f6
commit abc2335ea2
1 changed files with 23 additions and 1 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

24
CLAUDE.md
View file

@ -363,10 +363,32 @@ User registration inside Claude Code:
# ZIP channel (typically via a SessionStart hook that unpacks into ./marketplace/)
curl -H "Authorization: Bearer $AGNES_PAT" https://agnes.example.com/marketplace.zip
# Git channel — one-time registration
# Git channel — one-time registration. Two paths; pick the first that works.
# (a) Direct registration — preferred when it works.
/plugin marketplace add https://x:$AGNES_PAT@agnes.example.com/marketplace.git/
# (b) Two-step fallback — required when (a) fails. Bun-compiled `claude` on
# macOS / Windows ignores the OS trust store and CA env vars on the
# marketplace HTTPS path, so direct add can fail with TLS errors against
# a private-CA Agnes instance even when system tools work fine. System
# `git` honors GIT_SSL_CAINFO + the OS trust store, so cloning manually
# and pointing Claude Code at the local clone sidesteps the Bun TLS path
# entirely.
git clone https://x:$AGNES_PAT@agnes.example.com/marketplace.git/ ~/agnes-marketplace
claude plugin marketplace add ~/agnes-marketplace
# Optional hardening: strip the PAT from the cloned repo's origin so it
# doesn't sit in plaintext at ~/agnes-marketplace/.git/config — re-clone via
# the dashboard's setup flow when the PAT rotates.
git -C ~/agnes-marketplace remote set-url origin https://agnes.example.com/marketplace.git/
```
The dashboard-served setup payload (see `app/web/setup_instructions.py`) already
branches between (a) and (b) automatically based on platform when a private CA
is in play. The block above is the manual equivalent for users registering
outside that flow (e.g. operators bringing up a new instance, or
analysts whose first attempt failed and need to retry by hand).
## Hybrid Queries (BigQuery + Local)
For tables too large to sync locally, use hybrid queries that JOIN local data with on-demand BigQuery results: