Quick Start

Get your AI agent connected to the gateway in under 5 minutes.

Prerequisites

You need the following installed:

Tool	Check	Purpose
`bash`	`bash --version`	Script runtime (4.0+ recommended)
`curl`	`curl --version`	HTTP requests
`jq`	`jq --version`	JSON parsing
`python3`	`python3 --version`	Token extraction and SSO server
`base64`	`echo test \| base64`	JWT decoding

You also need one of the following for authentication:

M2M credentials: GATEWAY_CLIENT_ID, GATEWAY_CLIENT_SECRET, and GATEWAY_TOKEN_ENDPOINT (from your team admin or terraform output)
SSO access: A Cognito user pool configured for browser-based login
Existing JWT: A valid access token obtained through another method

Step 1: Run the Setup Wizard

The interactive wizard handles everything: connectivity testing, authentication, agent configuration, and an optional inference test.

./scripts/gateway-setup.sh

The wizard walks through six steps:

Gateway connection — Enter the gateway URL, verify connectivity
Authentication — Choose M2M credentials, SSO browser login, or paste an existing JWT
Token validation — Confirm the token works against the gateway
Agent selection — Pick your AI agent (Claude Code, OpenCode, Goose, Continue.dev, LangChain, or custom)
Configuration — Get the exact environment variables and config files for your agent
Inference test — Optionally send a test prompt to verify end-to-end

Step 2: Apply the Configuration

Copy the environment variables the wizard outputs into your shell profile (~/.zshrc or ~/.bashrc), then reload:

source ~/.zshrc

For agents that need config files (OpenCode, Continue.dev, Codex CLI), create or edit the files as shown by the wizard.

Step 3: Verify

Run the health check to confirm everything is working:

# Basic connectivity check
./scripts/check-health.sh --url "$GATEWAY_URL"

# Full check with authentication
TOKEN=$(./scripts/get-gateway-token.sh)
TOKEN="$TOKEN" ./scripts/check-health.sh --url "$GATEWAY_URL" --token "$TOKEN"

# Include provider checks
TOKEN="$TOKEN" ./scripts/check-health.sh --url "$GATEWAY_URL" --token "$TOKEN" --providers

What Each Script Does

Script	Purpose
`scripts/gateway-setup.sh`	Interactive onboarding wizard
`scripts/get-gateway-token.sh`	Fetch a Cognito M2M access token (client_credentials grant)
`scripts/sso-login.sh`	SSO browser login flow (opens browser, captures callback)
`scripts/check-health.sh`	Health check: connectivity, auth, token details, provider status

Next Steps

Authentication — How the Cognito M2M auth flow works
Agent Setup — Detailed per-agent configuration
Troubleshooting — Common errors and fixes