agentleFS
aws-samplesaws-samples/anthropic-on-aws/claude-apps-gateway/CLAUDE.md

anthropic-on-aws / claude-apps-gateway

CLAUDE.md443 starsChanged 3 months agoMIT-0View on GitHub

A worked example for deploying the Claude apps gateway on AWS. It is reference material for customer-managed infrastructure — a working example, not a supported production artifact. Every doc and README must preserve that framing. The Claude apps gateway is a self-hosted service built into the claude binary (claude gateway --config gateway.yaml). It sits between developers' Claude Code clients and a model provider: developers sign in via corporate OIDC SSO instead of holding API keys, the gateway holds the upstream…

  • Installs packages

The file

We split this CLAUDE.md into the rules it gives an agent

2 rules. About 0 are common, 2 are distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    No live AWS account is wired up here, so verification is local/static:

    line 125
  2. Distinctive:

    Verify reviewers' comments against the code the same way before applying them, and push back where they're wrong.

    line 175

≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this repo is

A worked example for deploying the Claude apps gateway on AWS. It is reference material for customer-managed infrastructure — a working example, not a supported production artifact. Every doc and README must preserve that framing.

The Claude apps gateway is a self-hosted service built into the claude binary (claude gateway --config gateway.yaml). It sits between developers' Claude Code clients and a model provider: developers sign in via corporate OIDC SSO instead of holding API keys, the gateway holds the upstream credential, enforces per-IdP-group model access + managed settings, and fans out OTLP telemetry. This repo's upstream is Amazon Bedrock.

The implementation is built out — setup.sh and the CDK app (cdk/) provision the Fargate track, with the EKS track documented in docs/. When adding or changing files, follow the existing structure.

Architecture

Two deployment tracks:

  • ECS Fargate behind an internal IPv4 ALB — the primary, fully-automated track, delivered as both setup.sh (idempotent aws-CLI) and a CDK app (cdk/, TypeScript).
  • EKS + IRSA — a documented-notes-only track in docs/eks-notes.md.

Shared data plane: RDS for PostgreSQL (private subnets, no public IP), Secrets Manager (jwt / oidc client secret / postgres-url / the gateway.yaml config itself), ECR for the image, and an IAM task role granting Bedrock invoke.

The CDK app and setup.sh provision the same Fargate deployment two ways — keep them in sync.

Non-obvious constraints (these break the gateway if missed)

  • Bedrock IAM needs two ARN families. Grant bedrock:InvokeModel + bedrock:InvokeModelWithResponseStream + bedrock:CountTokens (free token counts: aborted requests from 2.1.260, /context and large file reads from 2.1.295; where it fails, the gateway falls back to a billable max_tokens:1 invoke, so it's a cost nicety, not a correctness gate — model coverage is noted in cdk/lib/claude-gateway-stack.ts) on both inference-profile/global.anthropic.* and foundation-model/anthropic.*. Missing either yields 403s. The gateway uses global cross-region inference profiles (global.anthropic.*) so any Bedrock region works; the inference-profile ARN prefix must match the profile prefix in gateway.yaml's models: block (swap both to us./eu./au. together if you switch off global for data residency — jp. exists for some models too, but geo coverage varies per model, so confirm each id with aws bedrock list-inference-profiles rather than assuming a clean substitution).
  • Fargate, not EC2, is the primary track for a reason. On EC2-backed compute the default IMDSv2 hop limit of 1 blocks the in-container metadata call → every Bedrock request 502s with Could not load credentials from any providers. Fargate task roles avoid this (ECS container-credentials endpoint). The EKS notes must document the hop-limit fix.
  • Gateway hostname must resolve to private IPs only — Claude Code's /login rejects any public IP. Use an IPv4-only internal ALB: internal dual-stack ALBs return public-range AAAA records that the check rejects.
  • public_url drives everything. The gateway builds its OIDC redirect_uri and discovery doc only from listen.public_url, never from X-Forwarded-*. This forces a two-pass deploy: first pass provisions and prints the ALB hostname; set it as public_url (and register <public_url>/oauth/callback on the OIDC client), then redeploy.
  • Raise the ALB idle timeout (e.g. 3600s) or long streaming responses get cut off.
  • The container stopTimeout must outlast the gateway's SIGTERM drain. From 2.1.274 the gateway lets in-flight requests finish for up to 25s before exiting (CLAUDE_GATEWAY_DRAIN_TIMEOUT_MS); ECS SIGKILLs at stopTimeout, so a shorter value truncates the drain and a rolling deploy severs live streams — the same failure the raised ALB idle timeout exists to prevent. Both tracks pin it to 40s (CDK: a property override, since taskImageOptions exposes no stopTimeout; setup.sh: in the task-def JSON), and a CDK test asserts the web container's value is above 25. Raise both together, never one.
  • Config secret guard: setup.sh must refuse to publish gateway.yaml while any REPLACE_ME placeholder remains.
  • Container image: distroless glibc base (gcr.io/distroless/cc-debian12:nonroot) around the pinned linux-x64 native claude binary; build --platform=linux/amd64 --provenance=false (buildx OCI image indexes are rejected by some runtimes). CLAUDE_CONFIG_DIR=/tmp/.claude.
  • TLS is an imported ACM cert. CERT_ARN/certArn is required for pass 2; the ALB uses it as-is and the CLI pins its SHA-256 fingerprint on first /login (intended 1p behavior — the CLI pinning the authentic gateway). To skip the prompt, import a public ACM cert: DNS validation needs no public endpoint, so the ALB stays internal and the cert is browser-trusted. Keep setup.sh and CDK in sync. See the "TLS: bring an ACM cert" section of cdk/README.md.

Conventions

  • Secret expansion in gateway.yaml: ${ENV_VAR} (env injection, used on ECS) or ${file:/path} (mounted files, used on EKS via the Secrets Store CSI driver). Never inline secrets.
  • auth: {} in the Bedrock upstream means "use the AWS default credential chain" — i.e. the task role / IRSA. Prefer this over static keys everywhere.
  • Health: ALB target-group health check → GET /healthz (liveness). GET /readyz verifies the store (Postgres). Keep the target-group check on /healthz: liveness keeps replicas in rotation, whereas pointing it at /readyz would drain all replicas on a transient Postgres blip. Weigh that before changing the probe target.
  • setup.sh is idempotent (describe-before-create); set -euo pipefail; trap-clean partial binary downloads. Inputs are env vars with defaults (${VAR:-default}).

Scope guardrails: 1p-first (read before adding anything)

This sample teaches the supported Anthropic path on AWS. Anything that lags a 1p change misleads readers, because sample code looks authoritative. Before adding code, a script, or a doc paragraph, check each of these. If any applies, don't build it; write a short doc note that links the published Anthropic docs instead.

  • Wrapping or re-implementing an Anthropic product surface (admin API client, gateway config schema, CLI behavior, managed-settings keys). This becomes a second source of truth that goes stale on every product release. Helper scripts and admin CLIs are DIY tooling that customers own; they do not land in this tree. Moving them to workshop/ or docs/ is still hosting them.
  • Working around current product behavior: reverse-engineered schemas, "until X ships in-region" relays, version gates such as Desktop >= x, disabling a feature to dodge a provider 400. If truly unavoidable, quarantine it in a clearly labeled temporary section that names what supersedes it.
  • Shipping a finished surface Anthropic may own: dashboards, spend/usage UIs, management views. Keep such layers thin and explicitly "example". Show the data exists; don't render it.
  • Adding a capability rather than a fix. A new mode or branch must (a) unlock something the existing config can't already reach, (b) teach the 1p product rather than generic AWS, PKI, or DNS plumbing, and (c) justify its permanent maintenance cost. Concretely: TLS stays the single imported-cert CERT_ARN path, and the first-login fingerprint prompt is intended 1p behavior, not something to engineer around.
  • Prose restating product API behavior (wire formats, pagination quirks, field semantics) lags the same way code does. Keep notes thin and defer to the reference docs below as the only authority.

Fixes to real breakage (crash, broken link, failed deploy on a supported config) are always welcome and should not be bundled with a debatable feature in the same PR.

Verification

No live AWS account is wired up here, so verification is local/static:

  • Shell: bash -n cdk/scripts/*.sh, and shellcheck cdk/scripts/*.sh if available.
  • CDK (strongest automated check — type-checks TS + validates construct wiring without deploying): cd cdk && npm install && npx cdk synth -c imageReady=false (pass 1). Pass 2 needs the -c context listed at the top of cdk/bin/app.ts; add -c zoneId=... so synth skips the fromLookup credential call. Deploy a single stack with npx cdk deploy <StackName>.
  • Tests (run these after changing the stack or stamp-config.sh, and add cases when fixing a deployment trap): cd cdk && npm test (Jest + CDK assertions over the synthesized template — dual-ARN Bedrock policy, IPv4 internal ALB, /healthz probe, ADOT telemetry sidecar, createVpcEndpoints opt-out, imported-cert TLS), ./test/stamp-config.test.sh (dependency-free bash: placeholder guard + Google scope auto-injection), ./test/setup-helpers.test.sh (setup.sh's sourceable helpers — container-tool detection / --provenance gating + the OIDC-secret preflight), and ./test/deploy-helpers.test.sh (deploy.sh's pass-1 gate — the destructive branch's status allowlist, fail-closed status query, and leaving CDK-recoverable statuses to CDK rather than bailing). None needs an AWS account. CDK tests pass zoneId in the stack props to skip the fromLookup credential call.
  • Config: python3 -c 'import yaml; yaml.safe_load(open("cdk/gateway.yaml.example"))' (the ${...} placeholders are plain strings to YAML).
  • docker build is deferred — it needs the real pinned claude binary that setup.sh stages.

End-to-end smoke tests (against a real account + OIDC IdP) are the user's, per the gateway quickstart: /.well-known/oauth-authorization-server, /oauth/device_authorization, then the browser sign-in leg.

Before every PR push: re-check the whole diff

The checks above prove a change loads, synthesizes or parses, not that it does what the docs say. Small commits that each pass review can still add up to a wrong result: a markup applied twice, a config row that matches nothing. So before opening a PR, before every push to an open one, and before re-requesting review, re-check the whole diff against main on aws-samples (upstream/main in a fork), not just the latest commit:

  1. Run every check in this section on the final tree, not only the ones the last commit touched.
  2. Re-read each changed block as one unit, the way a reader will use it. Editing one line can change what the lines next to it mean.
  3. Run examples the way the docs tell users to. Uncomment config exactly as instructed and run it with claude gateway --config on the pinned version. Check the effect (the resulting rate, which row matches, which route is taken), not just that it boots.
  4. Check every identifier against what the sample ships. Model IDs and prefixes against the models: catalog (date suffixes included), plus keys and paths. Test exactly the values the docs name, not a convenient subset.
  5. Open every link and anchor the diff adds or touches, including cross-file §N references, which go stale when headings move.
  6. Re-check version claims against releases and changelog entries since the last push if the PR has been open a while, was rebased, or depends on another PR.
  7. Re-read the PR body against the final diff (file list, section numbers) and state which checks you ran.

Verify reviewers' comments against the code the same way before applying them, and push back where they're wrong.

Reference docs

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.