AI-CLI-Cloud

AI-CLI-Cloud is a portable Dev Container workstation for AI-assisted software, cloud, and infrastructure development.

It is designed to let an older or lightweight host machine run a modern Linux-based development environment with AI terminal assistants, cloud CLIs, GitHub tooling, Docker access, and Terraform support.

What is AI-CLI-Cloud?

AI-CLI-Cloud is not an application framework. It is a reusable development environment.

After opening this repository as a Dev Container, you can clone other trusted projects inside the workspace and use terminal-based AI assistants to inspect, edit, validate, and accelerate development work.

Typical use cases:

• AI-assisted code review and refactoring.
• Cloud infrastructure experiments.
• Terraform validation.
• AWS and Google Cloud terminal workflows.
• GitHub CLI operations.
• Multi-repository development from a consistent Linux environment.
• Modern CLI usage from older host systems that can still run Docker and VS Code Dev Containers.

Problem it solves

Modern AI and cloud CLIs often require newer operating systems, newer Node.js runtimes, or Linux-friendly tooling. AI-CLI-Cloud moves that tooling into a controlled container environment while keeping host credentials available through explicit convenience mounts.

The host provides Docker, VS Code, local credentials, and storage. The container provides the modern development runtime.

Environment architecture

Host machine
  └── Docker + VS Code Dev Containers
        └── AI-CLI-Cloud Linux devcontainer
              ├── Python 3.11
              ├── Node.js 20 LTS
              ├── Codex CLI
              ├── Claude Code
              ├── Gemini CLI
              ├── AWS CLI v2
              ├── Google Cloud CLI
              ├── GitHub CLI
              ├── Docker CLI
              └── Terraform

The devcontainer uses two persistence strategies:

• Named Docker volumes for AI CLI configuration and npm global packages.
• Host bind mounts for trusted local credentials such as AWS, Google Cloud, GitHub CLI, Git, and SSH.

Architecture diagram

The architecture diagram is available in both SVG and PNG formats. The SVG version is kept as the editable source, while the PNG export is used as the polished visual reference for README and documentation purposes.

Included stack

Area	Tooling
Base runtime	Python 3.11 on Debian Bookworm
JavaScript runtime	Node.js 20 LTS and npm
AI assistants	Codex CLI, Claude Code, Gemini CLI
Cloud	AWS CLI v2, Google Cloud CLI
Infrastructure	Terraform, terraform-docs, TFLint
Source control	Git, GitHub CLI, SSH
Containers	Docker CLI through Docker-outside-of-Docker
Utilities	curl, wget, jq, zip, unzip, tree, make, vim, nano, zsh

Host requirements

The host machine should have:

• Docker installed and running.
• VS Code or a compatible editor with Dev Containers support.
• Git.
• Internet access during the first build and post-create installation.
• Optional local credentials for AWS, Google Cloud, GitHub CLI, Git, and SSH.

Before opening the devcontainer, make sure these host paths exist if you want to use the convenience bind mounts:

mkdir -p ~/.aws ~/.config/gcloud ~/.config/gh ~/.ssh
touch ~/.gitconfig

Opening the devcontainer

Clone this repository:

git clone https://github.com/HubertRonald/AI-CLI-Cloud.git
cd AI-CLI-Cloud

Copy the environment template:

cp .env.example .env

Review the flags and profile names:

cat .env

Open the folder in VS Code and run:

Dev Containers: Reopen in Container

After the container finishes creating, validate the environment:

./scripts/check_environment.sh

Environment variables

AI CLI installation is controlled through .env.

Node, npm, and nvm compatibility

AI-CLI-Cloud uses the official Dev Containers Node feature, which installs Node.js through nvm.

For compatibility with nvm, this repository does not set NPM_CONFIG_PREFIX in the Dockerfile, shell profile, or Dev Container environment. npm-based AI CLIs are installed into the persistent npm volume using one-shot npm install --prefix commands.

No manual changes are required in the host shell configuration, such as ~/.zshrc or ~/.bashrc.

INSTALL_AI_CLIS_ON_CREATE=true
INSTALL_CODEX=true
INSTALL_CLAUDE=true
INSTALL_GEMINI=true

AWS and Google Cloud helpers also read .env:

GCLOUD_PERSONAL_CONFIG=personal
GCLOUD_COMPANY_CONFIG=
AWS_DEFAULT_PROFILE=default
AWS_DEFAULT_REGION=us-east-1
AWS_PERSONAL_PROFILE=personal
AWS_COMPANY_PROFILE=

The repository includes .env.example as a public template. The real .env file is ignored by Git.

Activating Codex CLI

Codex CLI is installed by scripts/install_ai_clis.sh when INSTALL_CODEX=true.

Run:

codex

Follow the authentication flow shown by the CLI. Codex configuration is persisted in the named Docker volume mounted at:

/home/vscode/.codex

Activating Claude Code

Claude Code is installed by scripts/install_ai_clis.sh when INSTALL_CLAUDE=true.

Run:

claude

Follow the browser or terminal authentication flow shown by the CLI. Claude configuration is persisted in the named Docker volume mounted at:

/home/vscode/.claude

Activating Gemini CLI

Gemini CLI is installed by scripts/install_ai_clis.sh when INSTALL_GEMINI=true.

Run:

gemini

Follow the authentication flow shown by the CLI. Gemini configuration is persisted in the named Docker volume mounted at:

/home/vscode/.gemini

Validating AWS CLI

AI-CLI-Cloud does not create or manage AWS identities. It reuses profiles available through the mounted host directory:

~/.aws -> /home/vscode/.aws

Check the current AWS context:

./scripts/aws_status.sh

Use a specific profile for the current shell:

source scripts/aws_use_profile.sh personal

For an AWS IAM Identity Center or SSO-based company profile, first configure it if needed:

aws configure sso --profile company-dev

Then activate and validate it:

source scripts/aws_use_profile.sh company-dev
aws sts get-caller-identity --profile company-dev

AWS_COMPANY_PROFILE is optional. Leave it empty if you do not use a fixed company profile name.

Validating Google Cloud CLI

AI-CLI-Cloud reuses the host Google Cloud SDK directory:

~/.config/gcloud -> /home/vscode/.config/gcloud

Check the active Google Cloud context:

./scripts/gcloud_status.sh

Activate your personal named configuration:

./scripts/gcloud_use_personal.sh

Activate a company named configuration only after setting GCLOUD_COMPANY_CONFIG in .env:

./scripts/gcloud_use_company.sh

Validating Terraform

Terraform is installed through the official Dev Container Feature configuration in .devcontainer/devcontainer.json.

Validate it with:

terraform version

When using Terraform with Google Cloud or AWS, always validate both CLI identity and application credentials before running plan or apply operations.

Validating GitHub CLI

GitHub CLI uses the host configuration mounted from:

~/.config/gh -> /home/vscode/.config/gh

Validate it with:

gh auth status

If needed, authenticate from inside the devcontainer:

gh auth login

Credential convenience mounts

AI-CLI-Cloud is designed for trusted personal development workflows. The devcontainer can mount selected host credentials into the Linux container so cloud and Git operations work immediately from the terminal.

The following host paths are mounted as convenience bind mounts:

Host path	Container path	Purpose
~/.aws	/home/vscode/.aws	AWS CLI profiles and credentials
~/.config/gcloud	/home/vscode/.config/gcloud	Google Cloud CLI accounts, projects, and configurations
~/.config/gh	/home/vscode/.config/gh	GitHub CLI authentication
~/.gitconfig	/home/vscode/.gitconfig	Git identity and preferences
~/.ssh	/home/vscode/.ssh	SSH keys for Git and remote access

This is convenient, but it is also powerful. Any code executed inside the devcontainer may be able to access these mounted credentials. Use this environment only with repositories you trust. For unknown or third-party repositories, create a separate sandbox devcontainer without cloud, GitHub, or SSH credential mounts.

Working with multiple Google Cloud identities

If your local Google Cloud SDK contains more than one identity, for example a personal account and a company account, the devcontainer will see the same accounts through the ~/.config/gcloud bind mount.

Use named gcloud configurations to avoid mixing contexts:

gcloud config configurations list
gcloud config configurations activate personal
gcloud config list
gcloud auth list
gcloud config get-value project

For company work:

gcloud config configurations activate company
gcloud config list
gcloud auth list
gcloud config get-value project

Before running Terraform, deployment scripts, or destructive cloud commands, always verify:

gcloud auth list
gcloud config get-value account
gcloud config get-value project

Application Default Credentials may differ from the active gcloud account. Validate them separately when using Terraform, Python SDKs, or Google client libraries:

gcloud auth application-default print-access-token >/dev/null && echo "ADC OK"

Working with multiple AWS profiles

AWS profile names are user-defined. This repository does not assume that a company profile exists.

The default .env.example keeps company profile values optional:

AWS_DEFAULT_PROFILE=default
AWS_PERSONAL_PROFILE=personal
AWS_COMPANY_PROFILE=

Use profile-specific commands when the operation matters:

aws sts get-caller-identity --profile personal
aws sts get-caller-identity --profile company-dev

To set a profile for the current shell session, source the helper script:

source scripts/aws_use_profile.sh company-dev

For AWS SSO profiles, the helper script attempts aws sso login --profile <profile> when an SSO profile is detected.

Security notes

Do not open untrusted repositories in this credential-enabled devcontainer.

Recommended safety practices:

• Use this environment for repositories you own or trust.
• Keep a separate sandbox devcontainer without credential bind mounts for unknown projects.
• Validate AWS and Google Cloud active contexts before deployment or destructive commands.
• Prefer least-privilege cloud roles.
• Avoid long-lived credentials when short-lived or SSO-based credentials are available.
• Never commit .env, cloud credentials, tokens, SSH keys, or generated authentication files.

Maintenance strategy

This repository is intentionally lightweight. Maintenance should focus on predictable upgrades and explicit version notes.

Recommended maintenance cadence:

• Review the base image periodically.
• Keep Python on a stable runtime line, currently 3.11.
• Keep Node.js on an LTS line, currently 20.
• Review AI CLI installation commands when upstream packages change.
• Rebuild the devcontainer after major Docker, VS Code, or Dev Container Feature updates.
• Record meaningful changes in CHANGELOG.md.

Terraform is installed through the Dev Container Feature in .devcontainer/devcontainer.json, not from the Dockerfile.

Roadmap

Potential future releases:

• Add Azure CLI as an optional profile or separate image variant.
• Add a sandbox variant without host credential bind mounts.
• Add PNG export for the architecture diagram after the SVG design is finalized.
• Add optional pre-commit hooks for shell formatting and Markdown linting.
• Add version-pinned Terraform variants for stricter reproducibility.

Repository credit

Designed and built with ♥ and AI assistance by Hubert Ronald.

This devcontainer was inspired by the RetainAI development environment foundation: HubertRonald/RetainAI .devcontainer.

License

This project is licensed under the MIT License. See LICENSE for details.