From 66643b1ee67f26107ce7d1eab3acc28fae57ca5d Mon Sep 17 00:00:00 2001 From: suryaiyer95 Date: Mon, 13 Apr 2026 16:55:25 -0700 Subject: [PATCH 1/3] docs: add Amazon Bedrock custom endpoints guide and fix provider key - Add dedicated guide for custom Bedrock endpoints (API gateways, proxies, VPC endpoints) covering bearer token auth, AWS credential chain, config structure, cross-region model ID prefixing, and troubleshooting - Fix provider key from incorrect `bedrock` to `amazon-bedrock` across all docs (providers.md, quickstart.md, models.md) to match actual code - Update config examples to use `options` nesting structure matching the provider implementation - Add nav entry under Configure > LLMs Co-Authored-By: Claude Opus 4.6 --- .../configure/bedrock-custom-endpoints.md | 182 ++++++++++++++++++ docs/docs/configure/models.md | 2 +- docs/docs/configure/providers.md | 34 +++- docs/docs/getting-started/quickstart.md | 15 +- docs/mkdocs.yml | 1 + 5 files changed, 220 insertions(+), 14 deletions(-) create mode 100644 docs/docs/configure/bedrock-custom-endpoints.md diff --git a/docs/docs/configure/bedrock-custom-endpoints.md b/docs/docs/configure/bedrock-custom-endpoints.md new file mode 100644 index 0000000000..853d4acc3b --- /dev/null +++ b/docs/docs/configure/bedrock-custom-endpoints.md @@ -0,0 +1,182 @@ +# Amazon Bedrock Custom Endpoints + +This guide covers using Altimate Code with a custom Amazon Bedrock endpoint — such as a corporate API gateway, reverse proxy, or VPC endpoint that sits in front of Bedrock. + +## When to use this + +Use this setup when your organization: + +- Routes Bedrock traffic through a centralized API gateway +- Requires a custom domain or proxy for compliance / network policy +- Uses a bearer token instead of standard AWS IAM credentials + +## Prerequisites + +You need one of the following: + +- A **bearer token** issued by your gateway (most common for custom endpoints) +- Standard **AWS credentials** (access key, SSO profile, IAM role) if your gateway still delegates to the AWS credential chain + +## Step 1: Set up authentication + +=== "Bearer Token" + + Export the token as an environment variable. Add this to your shell profile (`~/.zshrc`, `~/.bashrc`, or equivalent): + + ```bash + export AWS_BEARER_TOKEN_BEDROCK="your-bearer-token-here" + ``` + + Then reload your shell: + + ```bash + source ~/.zshrc + ``` + + !!! tip + If your organization uses the Altimate Code TUI, you can store the token via `altimate-code auth amazon-bedrock` instead of exporting it in your shell profile. + +=== "AWS Credential Chain" + + If your gateway forwards standard AWS credentials, no extra auth setup is needed. Altimate Code uses the standard AWS credential chain: + + 1. `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` environment variables + 2. `AWS_PROFILE` (named profile from `~/.aws/config`) + 3. IAM role / SSO session + 4. Web identity token (`AWS_WEB_IDENTITY_TOKEN_FILE`) + 5. ECS / EKS container credentials + + To use a specific AWS profile, set it in the config: + + ```json + { + "provider": { + "amazon-bedrock": { + "options": { + "profile": "my-sso-profile" + } + } + } + } + ``` + +!!! note + When a bearer token is present, the AWS credential chain is bypassed entirely. The bearer token always takes precedence. + +## Step 2: Create the config + +Create or edit `~/.config/altimate-code/altimate-code.json`: + +```json +{ + "model": "amazon-bedrock/anthropic.claude-sonnet-4-6-v1", + "provider": { + "amazon-bedrock": { + "options": { + "baseURL": "https://your-gateway.example.com/bedrock/v1", + "region": "us-east-1" + } + } + } +} +``` + +| Field | Description | +|-------|-------------| +| `model` | The model to use, prefixed with `amazon-bedrock/`. | +| `baseURL` | Your custom gateway URL. Replace with your organization's endpoint. | +| `region` | The AWS region your gateway targets (e.g., `us-east-1`, `eu-west-1`). | + +!!! info "The `baseURL` path" + The path portion of the `baseURL` (e.g., `/bedrock/v1`) depends entirely on how your API gateway is configured. Ask your platform team for the correct URL — there is no universal standard path. + +### Config scope + +| Config location | Scope | +|-----------------|-------| +| `~/.config/altimate-code/altimate-code.json` | Global — applies to all projects | +| `altimate-code.json` in a project root | Project — overrides global config for that project | + +## Step 3: Launch + +```bash +altimate-code +``` + +The status bar should display your selected model under Amazon Bedrock. + +## Cross-region model ID prefixing + +Altimate Code automatically prepends a region prefix to model IDs for cross-region inference. For example, with `region: "us-east-1"` the model ID `anthropic.claude-sonnet-4-6-v1` is sent to the gateway as `us.anthropic.claude-sonnet-4-6-v1`. + +| Your region | Prefix applied | +|-------------|---------------| +| `us-*` (except GovCloud) | `us.` | +| `eu-*` | `eu.` | +| `ap-northeast-1` (Tokyo) | `jp.` | +| `ap-southeast-2`, `ap-southeast-4` (Australia) | `au.` | +| Other `ap-*` | `apac.` | + +**If your gateway expects the prefixed ID** (e.g., `us.anthropic.claude-sonnet-4-6-v1`), no changes are needed — this is the default behavior. + +**If your gateway expects the unprefixed ID**, include the prefix in the model name yourself to skip auto-prefixing: + +```json +{ + "model": "amazon-bedrock/us.anthropic.claude-sonnet-4-6-v1" +} +``` + +When the model ID already starts with a recognized prefix (`us.`, `eu.`, `global.`, `jp.`, `apac.`, `au.`), auto-prefixing is skipped and the ID is passed through as-is. + +## Troubleshooting + +### Verify credentials and config + +```bash +altimate-code providers list +``` + +This shows all stored credentials and active environment variables. You should see `Amazon Bedrock` listed under credentials or environment. + +### Check config resolution + +Look for these lines in the logs (`~/.local/share/altimate-code/log/*.log`): + +| Log line | Meaning | +|----------|---------| +| `service=config path=...altimate-code.json loading` | Config file is being read | +| `service=provider providerID=amazon-bedrock found` | Provider detected successfully | +| `service=provider providerID=amazon-bedrock` + error | Auth or endpoint failure | + +### Enable debug logging + +For detailed output including credential chain steps and SDK-level request info: + +```bash +altimate-code --log-level DEBUG +``` + +## Full config reference + +```json +{ + "model": "amazon-bedrock/anthropic.claude-sonnet-4-6-v1", + "provider": { + "amazon-bedrock": { + "options": { + "baseURL": "https://your-gateway.example.com/bedrock/v1", + "region": "us-east-1", + "profile": "my-aws-profile" + } + } + } +} +``` + +| Option | Type | Description | +|--------|------|-------------| +| `baseURL` | `string` | Custom API gateway URL. Overrides the default Bedrock endpoint. | +| `endpoint` | `string` | Alias for `baseURL`. If both are set, `endpoint` takes precedence. | +| `region` | `string` | AWS region. Falls back to `AWS_REGION` env var, then `us-east-1`. | +| `profile` | `string` | AWS named profile. Falls back to `AWS_PROFILE` env var. | diff --git a/docs/docs/configure/models.md b/docs/docs/configure/models.md index 6b13c7ffcf..726832ab5b 100644 --- a/docs/docs/configure/models.md +++ b/docs/docs/configure/models.md @@ -73,7 +73,7 @@ Models are referenced as `provider/model-name`: |----------|--------------| | Anthropic | `anthropic/claude-sonnet-4-6` | | OpenAI | `openai/gpt-4o` | -| AWS Bedrock | `bedrock/anthropic.claude-sonnet-4-6-v1` | +| Amazon Bedrock | `amazon-bedrock/anthropic.claude-sonnet-4-6-v1` | | Azure | `azure/gpt-4o` | | Google | `google/gemini-2.5-pro` | | Ollama | `ollama/llama3.1` | diff --git a/docs/docs/configure/providers.md b/docs/docs/configure/providers.md index c4aceb52ef..aba05f0c78 100644 --- a/docs/docs/configure/providers.md +++ b/docs/docs/configure/providers.md @@ -69,25 +69,45 @@ Available models: `claude-opus-4-6`, `claude-sonnet-4-6`, `claude-haiku-4-5-2025 } ``` -## AWS Bedrock +## Amazon Bedrock ```json { "provider": { - "bedrock": { - "region": "us-east-1", - "accessKeyId": "{env:AWS_ACCESS_KEY_ID}", - "secretAccessKey": "{env:AWS_SECRET_ACCESS_KEY}" + "amazon-bedrock": { + "options": { + "region": "us-east-1" + } } }, - "model": "bedrock/anthropic.claude-sonnet-4-6-v1" + "model": "amazon-bedrock/anthropic.claude-sonnet-4-6-v1" } ``` Uses the standard AWS credential chain. Set `AWS_PROFILE` or provide credentials directly. !!! note - If you have AWS SSO or IAM roles configured, Bedrock will use your default credential chain automatically, so no explicit keys are needed. + If you have AWS SSO, IAM roles, or environment credentials (`AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY`) configured, Bedrock will use your default credential chain automatically. + +### Custom Endpoints (API Gateways) + +If your organization routes Bedrock traffic through a custom API gateway or proxy, set the `baseURL` in the provider options: + +```json +{ + "provider": { + "amazon-bedrock": { + "options": { + "baseURL": "https://your-gateway.example.com/v1", + "region": "us-east-1" + } + } + }, + "model": "amazon-bedrock/anthropic.claude-sonnet-4-6-v1" +} +``` + +For a complete walkthrough — including bearer token authentication, cross-region model IDs, and troubleshooting — see the [Amazon Bedrock Custom Endpoints guide](bedrock-custom-endpoints.md). ## Azure OpenAI diff --git a/docs/docs/getting-started/quickstart.md b/docs/docs/getting-started/quickstart.md index a62fff4ace..551aaa6dc8 100644 --- a/docs/docs/getting-started/quickstart.md +++ b/docs/docs/getting-started/quickstart.md @@ -75,21 +75,24 @@ Switch providers at any time by updating the `provider` and `model` fields in `a } ``` -=== "AWS Bedrock" +=== "Amazon Bedrock" ```json { "provider": { - "bedrock": { - "region": "us-east-1", - "accessKeyId": "{env:AWS_ACCESS_KEY_ID}", - "secretAccessKey": "{env:AWS_SECRET_ACCESS_KEY}" + "amazon-bedrock": { + "options": { + "region": "us-east-1" + } } }, - "model": "bedrock/anthropic.claude-sonnet-4-6-v1" + "model": "amazon-bedrock/anthropic.claude-sonnet-4-6-v1" } ``` + Uses the standard AWS credential chain (`AWS_PROFILE`, `AWS_ACCESS_KEY_ID`/`AWS_SECRET_ACCESS_KEY`, IAM roles, SSO). + For custom API gateways, see [Bedrock Custom Endpoints](../configure/bedrock-custom-endpoints.md). + === "Azure OpenAI" ```json diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 88310510d4..92c2a529a9 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -119,6 +119,7 @@ nav: - LLMs: - Providers: configure/providers.md - Models: configure/models.md + - Bedrock Custom Endpoints: configure/bedrock-custom-endpoints.md - MCPs & ACPs: - MCP Servers: configure/mcp-servers.md - ACP Support: configure/acp.md From 844fd65ccaeb0fd5ba85fcbd63d7983076d65fb4 Mon Sep 17 00:00:00 2001 From: suryaiyer95 Date: Mon, 13 Apr 2026 21:23:54 -0700 Subject: [PATCH 2/3] docs: address PR review comments on Bedrock docs - Fix CLI auth command: `altimate-code auth login --provider amazon-bedrock` - Clarify cross-region prefixing is conditional on model family + region - Add "Models prefixed" column to region prefix table - Fix backwards "unprefixed ID" guidance with accurate pass-through behavior - Add warning about no option to disable auto-prefixing - Fix log line format to match actual `service=config loading config from ...` - Remove ambiguous "provide credentials directly" wording - Fix Provider Options Reference: `options.region/profile/baseURL` not top-level Co-Authored-By: Claude Opus 4.6 --- .../configure/bedrock-custom-endpoints.md | 33 +++++++++++-------- docs/docs/configure/providers.md | 8 ++--- 2 files changed, 24 insertions(+), 17 deletions(-) diff --git a/docs/docs/configure/bedrock-custom-endpoints.md b/docs/docs/configure/bedrock-custom-endpoints.md index 853d4acc3b..8befee8722 100644 --- a/docs/docs/configure/bedrock-custom-endpoints.md +++ b/docs/docs/configure/bedrock-custom-endpoints.md @@ -34,7 +34,7 @@ You need one of the following: ``` !!! tip - If your organization uses the Altimate Code TUI, you can store the token via `altimate-code auth amazon-bedrock` instead of exporting it in your shell profile. + If your organization uses the Altimate Code TUI, you can store the token via `altimate-code auth login --provider amazon-bedrock` instead of exporting it in your shell profile. === "AWS Credential Chain" @@ -107,19 +107,23 @@ The status bar should display your selected model under Amazon Bedrock. ## Cross-region model ID prefixing -Altimate Code automatically prepends a region prefix to model IDs for cross-region inference. For example, with `region: "us-east-1"` the model ID `anthropic.claude-sonnet-4-6-v1` is sent to the gateway as `us.anthropic.claude-sonnet-4-6-v1`. +Altimate Code may prepend a region prefix to model IDs for cross-region inference when the selected model and region require it. For example, with `region: "us-east-1"` the model ID `anthropic.claude-sonnet-4-6-v1` is sent to the gateway as `us.anthropic.claude-sonnet-4-6-v1`. -| Your region | Prefix applied | -|-------------|---------------| -| `us-*` (except GovCloud) | `us.` | -| `eu-*` | `eu.` | -| `ap-northeast-1` (Tokyo) | `jp.` | -| `ap-southeast-2`, `ap-southeast-4` (Australia) | `au.` | -| Other `ap-*` | `apac.` | +Prefixing is conditional on **both** the region and the model family: -**If your gateway expects the prefixed ID** (e.g., `us.anthropic.claude-sonnet-4-6-v1`), no changes are needed — this is the default behavior. +| Your region | Prefix | Models prefixed | +|-------------|--------|-----------------| +| `us-*` (except GovCloud) | `us.` | Claude, Nova, DeepSeek | +| `eu-*` | `eu.` | Claude, Nova Lite/Micro, Llama 3, Pixtral | +| `ap-northeast-1` (Tokyo) | `jp.` | Claude, Nova Lite/Micro/Pro | +| `ap-southeast-2`, `ap-southeast-4` (Australia) | `au.` | Claude Sonnet 4.5, Claude Haiku | +| Other `ap-*` | `apac.` | Claude, Nova Lite/Micro/Pro | -**If your gateway expects the unprefixed ID**, include the prefix in the model name yourself to skip auto-prefixing: +Models not listed in the table for a given region are **not** prefixed. + +**If your gateway expects the prefixed ID** (e.g., `us.anthropic.claude-sonnet-4-6-v1`), no changes are needed — this is the default behavior for supported models. + +**If your gateway handles routing independently and expects the bare model ID**, you can force a specific model ID by including a recognized prefix yourself: ```json { @@ -127,7 +131,10 @@ Altimate Code automatically prepends a region prefix to model IDs for cross-regi } ``` -When the model ID already starts with a recognized prefix (`us.`, `eu.`, `global.`, `jp.`, `apac.`, `au.`), auto-prefixing is skipped and the ID is passed through as-is. +When the model ID already starts with a recognized prefix (`us.`, `eu.`, `global.`, `jp.`, `apac.`, `au.`), auto-prefixing is skipped and the ID is passed through as-is. Note that this does **not** strip the prefix — the full prefixed ID is what gets sent to the gateway. + +!!! warning + There is currently no config option to disable auto-prefixing entirely. If your gateway requires bare (unprefixed) model IDs and the model would normally be prefixed, contact your platform team or open an issue. ## Troubleshooting @@ -145,7 +152,7 @@ Look for these lines in the logs (`~/.local/share/altimate-code/log/*.log`): | Log line | Meaning | |----------|---------| -| `service=config path=...altimate-code.json loading` | Config file is being read | +| `service=config loading config from ...altimate-code.json` | Config file is being read | | `service=provider providerID=amazon-bedrock found` | Provider detected successfully | | `service=provider providerID=amazon-bedrock` + error | Auth or endpoint failure | diff --git a/docs/docs/configure/providers.md b/docs/docs/configure/providers.md index aba05f0c78..af2355af91 100644 --- a/docs/docs/configure/providers.md +++ b/docs/docs/configure/providers.md @@ -84,7 +84,7 @@ Available models: `claude-opus-4-6`, `claude-sonnet-4-6`, `claude-haiku-4-5-2025 } ``` -Uses the standard AWS credential chain. Set `AWS_PROFILE` or provide credentials directly. +Uses the standard AWS credential chain: environment variables (`AWS_ACCESS_KEY_ID`/`AWS_SECRET_ACCESS_KEY`), named profiles (`AWS_PROFILE`), SSO sessions, IAM roles, and container credentials. !!! note If you have AWS SSO, IAM roles, or environment credentials (`AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY`) configured, Bedrock will use your default credential chain automatically. @@ -330,8 +330,8 @@ The `small_model` is used for lightweight tasks like summarization and context c | `baseURL` | `string` | Custom API endpoint URL | | `api` | `string` | API type (e.g., `"openai"` for compatible endpoints) | | `headers` | `object` | Custom HTTP headers to include with requests | -| `region` | `string` | AWS region (Bedrock only) | -| `accessKeyId` | `string` | AWS access key (Bedrock only) | -| `secretAccessKey` | `string` | AWS secret key (Bedrock only) | +| `options.region` | `string` | AWS region (Amazon Bedrock only, default: `us-east-1`) | +| `options.profile` | `string` | AWS named profile (Amazon Bedrock only) | +| `options.baseURL` | `string` | Custom endpoint URL for Bedrock gateway/proxy (Amazon Bedrock only) | | `project` | `string` | GCP project ID (Google Vertex AI only) | | `location` | `string` | GCP region (Google Vertex AI only, default: `us-central1`) | From 56334d2a36cadd8919ce8813df18a2844d5cbbe3 Mon Sep 17 00:00:00 2001 From: suryaiyer95 Date: Mon, 13 Apr 2026 21:32:29 -0700 Subject: [PATCH 3/3] docs: fix contradictory 'bare model ID' guidance in prefix section --- docs/docs/configure/bedrock-custom-endpoints.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/configure/bedrock-custom-endpoints.md b/docs/docs/configure/bedrock-custom-endpoints.md index 8befee8722..85fffb8925 100644 --- a/docs/docs/configure/bedrock-custom-endpoints.md +++ b/docs/docs/configure/bedrock-custom-endpoints.md @@ -123,7 +123,7 @@ Models not listed in the table for a given region are **not** prefixed. **If your gateway expects the prefixed ID** (e.g., `us.anthropic.claude-sonnet-4-6-v1`), no changes are needed — this is the default behavior for supported models. -**If your gateway handles routing independently and expects the bare model ID**, you can force a specific model ID by including a recognized prefix yourself: +**If your gateway requires a specific prefixed model ID**, you can force that exact ID by including the recognized prefix yourself: ```json {