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
npx -y skills add pleaseai/shunt --skill run-claude-gateway-refAssembled 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) claudebinary ≥ 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/settingsbody:{"uuid":"sha256:…","checksum":"sha256:…","settings":{<managed-settings.json>}},ETag= checksum,If-None-Match→ 304. Withtelemetry.forward_toset 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 policyenv.- 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 sayssignals enabled: metricsfor a bareforward_toentry. /v1/modelsis filtered by the caller's policyavailableModels; full Anthropic shape (type,has_more,first_id,last_id).- Error envelope adds top-level
request_idalongside{"type":"error","error":{…}}. GET /user/bootstrap(new, Claude Desktop): 404not_found_errorunless a policy carries adesktop:block.
Gotchas
POST /deviceis CSRF-guarded: withoutOrigin+Referer+Sec-Fetch-Site: same-originit returns 200 with "request came from another site and was blocked" instead of the 302 to the IdP. The audit log showsdevice.verify result=csrf_rejected.- The
gw_devcookie from the/devicePOST must be replayed on/oauth/callbackor the device grant is never approved. - Dex
latest(master) hangs forever on refresh (memory AND sqlite3 storage) → gatewaysession.refreshfails with "timed out after 3500ms" and the client getsinvalid_grant. Pinv2.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 -wwrite into a JSON capture file — it corrupts the JSON and the nextpython3 json.loadfails with "Extra data". - The dummy
upstreamsAPI key boots fine; only/v1/messagesinference 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-dexand rerunup(pulls v2.44.0).device POST did not redirectfrom 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.logfirst.