Getting Started

This guide walks you through deploying Claude Code AWS Gateway (CCAG) and connecting Claude Code to it.

Prerequisites

• AWS account with Bedrock model access enabled (Claude models must be enabled in the Bedrock console)
• AWS CLI v2 configured with credentials
• Docker installed and running

Deployment Options

CCAG supports two deployment models:

	Docker Compose	AWS CDK
Best for	Solo users, small teams, evaluation	Teams needing managed infrastructure
Infrastructure	Single host (Docker)	ECS Fargate + RDS + ALB
Database	Containerized Postgres	RDS Postgres (managed)
Load balancing	None (single instance)	ALB with health checks
Autoscaling	Manual	CPU/memory-based
TLS	Self-signed or bring your own	ACM certificate (auto-provisioned)
Custom domain	Manual DNS	Route53 (automatic)
Prerequisites	Docker	Docker, Node.js 18+, AWS CDK

Option A: Docker Compose

cd claude-code-aws-gateway
cp .env.example .env

Edit .env. At minimum, set your AWS region:

AWS_REGION=us-east-1
# AWS_PROFILE=default        # uncomment if using named profiles
ADMIN_PASSWORD=changeme       # change the default admin password

AWS credentials are passed through from your host via the ~/.aws volume mount in docker-compose.yml. The gateway needs Bedrock access, so ensure your credentials are configured.

Credential sources (in order of precedence):

• Environment variables (AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY) in .env
• ~/.aws/credentials (static keys or credential_process)
• ~/.aws/config with SSO (aws sso login — ensure the SSO cache at ~/.aws/sso/cache/ is readable)

Common pitfalls:

• File permissions: the container runs as user proxy, so ~/.aws files must be world-readable (chmod 644)
• SSO tokens: aws sso login stores tokens in ~/.aws/sso/cache/, which is included in the mount
• Named profiles: set AWS_PROFILE=your-profile in .env if not using the default profile

Start the stack:

docker compose up -d

The gateway is now running at http://localhost:8080. Open http://localhost:8080/portal to access the admin portal.

Option B: AWS CDK (ECS Fargate + RDS)

See infra/README.md for the complete 9-step production deployment guide covering environment configuration, ECR setup, image builds, and CDK deploy.

This creates: VPC, ALB, ECS Fargate (ARM64/Graviton), RDS Postgres, autoscaling, CloudWatch alarms, and optional Route53/TLS.

First Login

Access the Admin Portal

Navigate to your gateway URL:

http://localhost:8080/portal            # Docker Compose
https://your-domain.com/portal          # CDK deployment

Bootstrap Admin Credentials

Default credentials:

• Username: admin
• Password: admin (or whatever you set in .env / CDK config)

Change the admin password immediately after first login.

Create Your First Virtual Key

1. Log in to the portal
2. Navigate to Keys
3. Click Create Key
4. Copy the generated key. It is shown only once.

Or via the API:

GATEWAY=http://localhost:8080

# Get a session token
TOKEN=$(curl -sf -X POST $GATEWAY/auth/login \
  -H "content-type: application/json" \
  -d '{"username":"admin","password":"admin"}' | grep -o '"token":"[^"]*"' | cut -d'"' -f4)

# Create a virtual key
curl -sf -X POST $GATEWAY/admin/keys \
  -H "content-type: application/json" \
  -H "authorization: Bearer $TOKEN" \
  -d '{"name":"my-key"}'

Connecting Claude Code

Log in to the admin portal and navigate to the Connect page. It provides a setup script that configures Claude Code automatically — creating a virtual API key and setting the required environment variables.

http://localhost:8080/portal            # Docker Compose
https://your-domain.com/portal          # CDK deployment

For OIDC/SSO authentication (browser-based login, no static API keys), see Authentication.

Verifying It Works

claude -p "Say exactly: gateway test successful" --max-turns 1

Check the gateway logs to confirm the request was proxied to Bedrock:

docker compose logs gateway    # Docker Compose

CLI Management Tool

CCAG includes a CLI (ccag) for managing a running gateway. Download the latest binary from GitHub Releases:

# macOS (Apple Silicon)
curl -fsSL https://github.com/antkawam/claude-code-aws-gateway/releases/latest/download/ccag-cli-darwin-aarch64.tar.gz | tar xz
sudo mv ccag /usr/local/bin/

# macOS (Intel)
curl -fsSL https://github.com/antkawam/claude-code-aws-gateway/releases/latest/download/ccag-cli-darwin-x86_64.tar.gz | tar xz
sudo mv ccag /usr/local/bin/

# Linux (x86_64)
curl -fsSL https://github.com/antkawam/claude-code-aws-gateway/releases/latest/download/ccag-cli-linux-x86_64.tar.gz | tar xz
sudo mv ccag /usr/local/bin/

# Linux (ARM64)
curl -fsSL https://github.com/antkawam/claude-code-aws-gateway/releases/latest/download/ccag-cli-linux-aarch64.tar.gz | tar xz
sudo mv ccag /usr/local/bin/

Windows binaries (.zip) are also available on the releases page.

Log in and manage your gateway:

ccag login --url http://localhost:8080
ccag keys list
ccag keys create --name "dev-key"
ccag config list

Set CCAG_URL to avoid repeating the --url flag. Update the CLI with ccag update. See CLI Reference for all commands.

Upgrading

Docker Compose

# Update to latest
docker compose pull && docker compose up -d

# Or pin to a specific version
CCAG_VERSION=1.1.0 docker compose up -d

CDK

cd infra
npx cdk deploy -c environment=prod -c imageTag=1.1.0

Database migrations run automatically on gateway startup. See Upgrading for details.

Next Steps

• Configuration: all configuration options
• Authentication: set up OIDC SSO
• CLI Reference: manage keys, users, settings
• FAQ: common questions and troubleshooting