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.4.1 · MIT licensed

What it helps with

• Understand your connection. See the AWS profile and region configured for Codex, and where credentials come from.
• Find a model. Browse Bedrock models for your AWS profile and region.
• Configure Codex. Answer guided questions, review changes before saving, and undo them if needed.
• Manage profile apps. List, close, or restart a saved desktop workspace while retaining its history.

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

Start a new Codex task, then try:

Which AWS profile and region is Codex configured to use?

Show me the Bedrock models for my development profile in us-west-2.

Help me choose a model and set up Codex to use it.

Codex asks for the details it needs and shows the proposed configuration changes before saving.

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.

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.

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.