AWS Helper for Codex

Connect Codex to Amazon Bedrock without editing configuration files by hand.

AWS Helper walks you through choosing an AWS connection, finding a model, and saving the settings Codex needs. Use it in your terminal or ask Codex to guide you through a conversation.

v0.5.0 · MIT licensed

What it helps with

• Open another workspace. Keep separate Codex desktop presets for different models or AWS connections, each with its own settings and history.
• Check connection health. See configured settings, credential sources, historical checks, and steps for recovering common errors.
• Compare models. Browse your regional catalog and compare documented capabilities across Mantle and Runtime.
• Estimate costs and inspect quotas. Compare token workloads using dated AWS prices and request a scoped quota lookup.
• Review and undo settings. Compare Codex configuration profiles, inspect change history, and preview a restore.

Get started

You'll need uv, Codex with its codex plugin commands, and AWS CLI v2.22+ for AWS requests.

uv tool install codex-aws-helper
codex-aws-helper plugin install

The package includes the helper and its plugin. Prebuilt wheels cover Apple Silicon and Intel Macs, plus Linux on ARM64 and x86-64. Wheel installation needs no Rust compiler, repository checkout, or GitHub login. Python 3.9+ is required by the package installer.

Using pip instead? Run python -m pip install codex-aws-helper in an activated virtual environment, then run the same plugin install command. The detailed installation guide is available with the other guides below.

Ask Codex

Once you've started a new Codex task with Amazon Bedrock, type this in the chat:

Use AWS Helper's aws-setup skill to show my configured AWS profile, region, and credential source.

You can also ask:

• “Create a Codex workspace named everyday using my development AWS profile, us-west-2, and openai.gpt-5.6-terra.”
• “Compare Terra and Astra on Mantle, including capabilities and estimated costs.”
• “Check my connection health and explain any findings.”
• “Show my recent configuration changes and preview undoing the latest one.”

Codex asks for the details it needs and shows the proposed changes before saving or opening a workspace. New desktop presets can install AWS Helper into their own Codex home. Sign-in stays in the terminal or browser.

See everyday plugin workflows for examples, profile terminology, cost assumptions, and recovery.

Use it in your terminal

codex-aws-helper

Choose one of five paths:

• Set up / open Codex — choose a connection and model, then review and launch.
• AWS connections — create a named AWS profile, sign in, or recover expired access.
• Models and access — browse regional models and explicitly test a selected model.
• My Codex apps — reopen saved workspaces with their history and settings.
• Troubleshoot — check local setup and create a redacted support report.

You can create an AWS connection before setting up Codex. AWS CLI handles company SSO and console sign-in. After choosing an existing profile, continue with it or explicitly renew a supported sign-in. The helper does not accept pasted access keys or session tokens, or write them to AWS files. AWS CLI manages its own sign-in caches; existing profiles remain intact.

Use an existing AWS profile requires a credential source you have already configured through AWS CLI or your company's approved tools. Stored keys and session tokens must already be populated and current; browser sign-in cannot renew them. SSO and console profiles can use Sign in / refresh.

Models and access guides you to a configured connection first. Confirm its AWS identity check to continue; failed checks offer recovery before opening the page. --offline shows cached information without verifying current access. Model listing and inference permissions are checked separately.

Enable Tab completion once, then open a new terminal tab:

codex-aws-helper completions --install

Tab suggests commands, flags, local profiles, regions, saved apps, and cached models without contacting AWS. Root help, -h, and --help describe the five everyday paths. Every command still has its full -h / --help, for example codex-aws-helper models --help. See shell setup for supported shells and activation in your current terminal.

Direct shortcuts remain available:

codex-aws-helper connections
codex-aws-helper models --browse
codex-aws-helper commands --all

My Codex apps → Open Codex reuses the saved workspace and leaves an already running app open. Scriptable lifecycle, plugin, and recovery tools are in the full command reference.

Update

uv tool upgrade codex-aws-helper
codex-aws-helper plugin install

Run plugin install again after upgrading or moving the helper. It refreshes the executable path and plugin files while preserving existing Codex settings and tool restrictions.

Before you try it

Sign-in stays in AWS CLI or your browser; you don't need to paste secret keys into chat. Saved settings take effect in new Codex sessions. Optional model tests use your AWS account and may incur normal Bedrock charges.

AWS integration is still a preview. macOS has the most runtime validation; Linux wheels have installation and synthetic test coverage. Automatic desktop launch is macOS-only and accepts specific inspected Codex builds. Model listings do not prove invocation access or native Codex compatibility, and Runtime configuration remains disabled. You can preview or save settings without using the desktop launcher.

Capability and pricing coverage is sourced and dated; missing facts remain unknown. Cost estimates are not your AWS bill, and quota limits do not show remaining capacity.

To remove the plugin, run codex-aws-helper plugin uninstall before uv tool uninstall codex-aws-helper. AWS credentials, provider settings, and recovery history remain available.

Learn more

All guides and the PDF below are included in the source archive on PyPI's Files tab, which you can download without a GitHub account. The GitHub links below require repository access while the repository is private.

• Installation and troubleshooting — pip, Cargo, local packages, and plugin setup.
• Sharing the plugin — install without a checkout and understand the OpenAI marketplace path.
• Compatibility — supported flows and measured limits.
• Terminal guide — sign-in, configuration, and everyday commands.
• Contributing — development, testing, and packaging.
• Codex development setup and PDF cheat sheet — remote hosts, worktrees, hooks, and project guidance.

An independent community project, distributed under the MIT license. The full license and dependency notices are included in every package.