agentsclimarketplace

Run claude gateway ref

Skill pleaseai/shunt/.claude/skills/run-claude-gateway-ref

Launch and drive a local reference Claude apps gateway (claude gateway + Dex + Postgres) to probe, capture, or re-verify the login / managed-settings / OTLP-telemetry wire protocol that shunt's gateway superset (login → managed/settings → telemetry, epic #87) must implement. Use to run the reference gateway, walk the device flow non-interactively, capture wire fixtures, or observe the telemetry relay.From its SKILL.md

Install
npx -y skills add pleaseai/shunt --skill run-claude-gateway-ref

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

SKILL.md

5.5 KB, as published. Nobody here has run it

Run the reference Claude apps gateway (protocol probe)

Spins up the real claude gateway (built into the claude binary) with a local Dex IdP and throwaway Postgres, then drives the full device-flow login non-interactively with curl — no browser needed. Use it to (re)capture the wire contract shunt mirrors: exact token JSON, /managed/settings body, env push, OTLP relay behavior.

Everything is driven by .claude/skills/run-claude-gateway-ref/driver.sh (paths relative to repo root). Backend note: curl is sufficient — the /device browser page is scriptable once you send same-origin CSRF headers.

Prerequisites

  • Docker running (pulls postgres:16-alpine, ghcr.io/dexidp/dex:v2.44.0)
  • claude binary ≥ 2.1.207 (verified with 2.1.211), python3, curl
  • Ports free: 8790 (gateway), 5556 (dex), 55432 (pg), 44318 (sink)

Run (agent path)

S=.claude/skills/run-claude-gateway-ref/driver.sh
$S up          # pg + dex containers, gateway on :8790, waits healthy
$S sink-start  # optional: local OTLP sink so the telemetry relay is observable
$S login       # full RFC 8628 device flow via curl → capture/token.json
$S probe       # captures protocol.md, managed_settings.json (+304), models.json,
               # refresh grant, POST /v1/metrics relay, /user/bootstrap
$S status      # health of all three processes
$S down        # kill gateway + sink, remove containers

Artifacts land in /tmp/shunt-gw-probe/capture/ (override root with GWREF_WORK). Gateway log: /tmp/shunt-gw-probe/gateway.log (audit events are JSON lines — evt: device.authorize, device.verify, session.mint, session.refresh, managed.serve, auth.denied). Sink log: /tmp/shunt-gw-probe/sink.log.

Login identity: [email protected] / password (Dex static user, no groups).

Verified wire facts (2026-07-16, gateway 2.1.211)

Captured live; these fill the gaps docs/gateway-protocol.md marks unspecified:

  • Token response (device grant AND refresh grant, same shape): {"access_token":"<HS256 JWT>","refresh_token":"<opaque>","token_type":"Bearer","expires_in":3600}. JWT claims: sub (IdP subject), email, name, aud=oidc client_id, iss=public_url. Refresh rotates the refresh token. Gateway refresh = refresh against the IdP (3500ms budget) + re-mint; IdP failure → 401 {"error":"invalid_grant"}.
  • /managed/settings body: {"uuid":"sha256:…","checksum":"sha256:…","settings":{<managed-settings.json>}}, ETag = checksum, If-None-Match → 304. With telemetry.forward_to set it pushes six env vars (docs say five): CLAUDE_CODE_ENABLE_TELEMETRY=1, OTEL_{METRICS,LOGS,TRACES}_EXPORTER=otlp, OTEL_EXPORTER_OTLP_ENDPOINT=<public_url>, OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf, merged with policy env.
  • Discovery includes undocumented gateway_protocol_version: 1, token_endpoint_auth_methods_supported: ["none"], scopes_supported.
  • IdP callback is {public_url}/oauth/callback (register in the IdP client).
  • Telemetry relay is verbatim — body forwarded byte-identical, no identity attributes stamped by the gateway; POST /v1/{metrics,logs,traces} returns 200 even when the destination is down. Boot log says signals enabled: metrics for a bare forward_to entry.
  • /v1/models is filtered by the caller's policy availableModels; full Anthropic shape (type, has_more, first_id, last_id).
  • Error envelope adds top-level request_id alongside {"type":"error","error":{…}}.
  • GET /user/bootstrap (new, Claude Desktop): 404 not_found_error unless a policy carries a desktop: block.

Gotchas

  • POST /device is CSRF-guarded: without Origin + Referer + Sec-Fetch-Site: same-origin it returns 200 with "request came from another site and was blocked" instead of the 302 to the IdP. The audit log shows device.verify result=csrf_rejected.
  • The gw_dev cookie from the /device POST must be replayed on /oauth/callback or the device grant is never approved.
  • Dex latest (master) hangs forever on refresh (memory AND sqlite3 storage) → gateway session.refresh fails with "timed out after 3500ms" and the client gets invalid_grant. Pin v2.44.0.
  • Loopback OIDC issuer is rejected by the SSRF guard unless CLAUDE_GATEWAY_ALLOW_LOOPBACK=1 (driver sets it). http:// public_url is accepted on loopback.
  • Don't let curl -w write into a JSON capture file — it corrupts the JSON and the next python3 json.load fails with "Extra data".
  • The dummy upstreams API key boots fine; only /v1/messages inference would fail. Postgres is required at boot (gateway runs 6 migrations).

Troubleshooting

  • refresh grant: 401 + gateway log "timed out after 3500ms" → your Dex image is unpinned/master; docker rm -f shunt-gw-dex and rerun up (pulls v2.44.0).
  • device POST did not redirect from the driver → CSRF headers missing (driver sends them; check you didn't proxy/strip them).
  • Boot fails on config: unknown keys fail fast with a field-level error; check /tmp/shunt-gw-probe/gateway.log first.

Keep looking

Skills are one crate of 613,297. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.