devcontainers

Create devcontainer configurations using duplocloud/devcontainers features.

Naming Conventions

The devcontainer name should be descriptive and creative. Use imagination to create a good name:

Sources for naming:

1. Repository name (e.g., terraform-duplocloud-components → "DuploCloud Components Devspace")
2. Project nickname from README (e.g., "Brook AI" → "Brook AI Devspace")
3. Company + purpose (e.g., "Acme Infrastructure Devspace")
4. Short descriptive name based on what the repo does

Format: "<Project Name> Devspace"

Examples:

• "DuploCloud IaC Devspace" - for infrastructure repos
• "Brook AI Development" - from README nickname
• "Playlab Platform Devspace" - from org/project name
• "Customer Portal Dev" - descriptive of purpose

If no clear name: Use repo directory name, title-cased, with "Devspace" suffix.

First Step: Read Project README

Always start by reading the project's README.md to understand:

• What the project does
• Technology stack
• Cloud provider (AWS/GCP)
• Any existing infrastructure references

Read: README.md (or README.rst, readme.md)

Feature Detection

Search the workspace for indicators to determine which features to include.

Detection Patterns

| Feature | Search For | Indicators | |---------|------------|------------| | terraform | *.tf, modules/, terraform/ | Terraform files present | | aws-cli | aws, s3://, AWS_, us-east, us-west | AWS references in code/config | | gcloud-cli | gcloud, gs://, GOOGLE_, gcp, GCP | GCP references in code/config | | kubernetes | kubectl, k8s, kubernetes, helm, Chart.yaml | K8s manifests or Helm charts | | github | .github/, github.com | GitHub workflows or references | | git | Commit signing needed, version tags | Team uses signed commits | | ai-claude | Team uses Claude | Anthropic AI preference | | ai-codex | Team uses ChatGPT/OpenAI | OpenAI preference | | ai-gemini | Team uses Gemini | Google AI preference | | onepassword-cli | Team uses 1Password | SSH key management needed | | direnv | .envrc files, per-dir env vars | direnv usage | | openvpn | VPN access needed | Private network access |

Search Commands

# Cloud detection
grep -r "aws\|s3://" --include="*.tf" --include="*.py" --include="*.yaml" .
grep -r "gcloud\|gs://" --include="*.tf" --include="*.py" --include="*.yaml" .

# Kubernetes detection
find . -name "*.yaml" -exec grep -l "kind:\|apiVersion:" {} \;
ls -la terraform/ modules/ 2>/dev/null

# Git provider
grep -r "github.com\|gitlab.com\|bitbucket.org" .

Required Feature

Always include duploctl - it's required for all other DuploCloud features:

"ghcr.io/duplocloud/devcontainers/duploctl:latest": {}

Feature Reference

| Feature | Purpose | When to Use | |---------|---------|-------------| | duploctl | DuploCloud CLI | Always required | | aws-cli | AWS CLI + JIT creds | AWS cloud projects | | gcloud-cli | Google Cloud CLI | GCP cloud projects | | terraform | Terraform + tf wrapper | Infrastructure as code | | kubernetes | kubectl + JIT kubeconfig | K8s workloads | | github | GitHub CLI + Copilot | GitHub repos | | git | Git config + signing + plugins | Commit signing, version bumping | | ai-claude | Anthropic Claude Code CLI | Claude AI assistance | | ai-codex | OpenAI Codex CLI | OpenAI/ChatGPT assistance | | ai-gemini | Google Gemini CLI | Gemini AI assistance | | onepassword-cli | 1Password + SSH keys | Team SSH management | | direnv | direnv + DuploCloud direnvrc | Per-directory env vars | | openvpn | OpenVPN client | VPN access to private networks |

Detailed options: See references/features.md

Config Folder Isolation Pattern

Important: All CLI configurations should be isolated to a workspace directory. This keeps state across container restarts and rebuilds.

Default folder: config/ (can also be .config, .secrets, .tmp, .dev - ask user if unclear)

Why This Matters

• Container rebuilds don't lose CLI state
• AWS credentials, kubeconfig, gcloud auth persist
• Team members can gitignore personal configs
• Clean separation of workspace vs container state

Environment Variables Point to Config Folder

"containerEnv": {
  "AWS_CONFIG_FILE": "${containerWorkspaceFolder}/config/aws",
  "KUBECONFIG": "${containerWorkspaceFolder}/config/kubeconfig.yaml",
  "CLOUDSDK_CONFIG": "${containerWorkspaceFolder}/config/gcloud",
  "GOOGLE_APPLICATION_CREDENTIALS": "${containerWorkspaceFolder}/config/gcloud/application_default_credentials.json",
  "DUPLO_CONFIG": "${containerWorkspaceFolder}/config/duplo.yaml",
  "CODEX_HOME": "${containerWorkspaceFolder}/config/.codex",
  "XDG_CONFIG_HOME": "${containerWorkspaceFolder}/config"
}

Config Folder Structure

config/
├── aws              # AWS CLI config
├── kubeconfig.yaml  # kubectl config
├── gcloud/          # gcloud SDK config
├── duplo.yaml       # duploctl config
├── op/              # 1Password CLI (via XDG_CONFIG_HOME)
└── .codex/          # Codex skills and config

Add to .gitignore

config/
!config/.gitkeep

init.sh Creates Config Folder

mkdir -p "${VSCODE_CWD}/config"

Environment Variable Strategy

Use ${localEnv:VAR_NAME} to pull values from the host machine into feature configuration. This allows team members to customize their devcontainer without modifying the shared config.

Required Local Environment Variables

These must be set on the host machine (in shell profile or .env):

| Variable | Purpose | Required | |----------|---------|----------| | DUPLO_HOST | DuploCloud portal URL | Yes | | DUPLO_TOKEN | DuploCloud API token | Yes | | GIT_USERNAME | Git commit author name | Recommended | | GIT_EMAIL | Git commit author email | Recommended | | OP_SSH_SECRET | 1Password SSH key name | If using 1Password | | OP_ACCOUNT | 1Password account domain | If using 1Password | | OP_VAULT_NAME | 1Password vault name | If using 1Password |

The .env File

Secrets are passed via .env file (never committed to git). The runArgs mounts this file:

"runArgs": [
  "--env-file=${localWorkspaceFolder}/.env"
]

Minimum .env contents:

DUPLO_HOST=https://yourportal.duplocloud.net
DUPLO_TOKEN=your-duplo-token

Add to .gitignore:

.env

Lifecycle Scripts

init.sh - Ensure .env Exists

Create .devcontainer/init.sh to bootstrap required files:

#!/usr/bin/env bash
set -e

echo "Init Devcontainer"

VSCODE_CWD=${VSCODE_CWD:-$PWD}

mkdir -p "${VSCODE_CWD}/config"

# Create .env file if it doesn't exist
if [ ! -f "${VSCODE_CWD}/.env" ]; then
  echo "Creating .env file with DUPLO credentials..."
  cat > "${VSCODE_CWD}/.env" << EOF
DUPLO_HOST=${DUPLO_HOST}
DUPLO_TOKEN=${DUPLO_TOKEN}
EOF
  echo ".env file created"
else
  echo ".env file already exists"
fi

post-start.sh - Post-Start Commands

Create .devcontainer/post-start.sh for commands after container starts:

#!/usr/bin/env bash
set -e

echo "Post start running"

# Add custom post-start commands here

Lifecycle Configuration

"initializeCommand": ".devcontainer/init.sh",
"postStartCommand": ".devcontainer/post-start.sh"

Basic Template

Default image: Python base (unless user specifies otherwise)

{
  "name": "<Project> Devspace",
  "image": "mcr.microsoft.com/vscode/devcontainers/python:3.12",
  "features": {
    "ghcr.io/devcontainers/features/docker-outside-of-docker:1": {
      "moby": "false"
    },
    "ghcr.io/duplocloud/devcontainers/duploctl:latest": {}
  },
  "runArgs": [
    "--env-file=${localWorkspaceFolder}/.env"
  ],
  "initializeCommand": ".devcontainer/init.sh",
  "postStartCommand": ".devcontainer/post-start.sh",
  "containerEnv": {
    "WORKSPACE_FOLDER": "${containerWorkspaceFolder}",
    "DUPLO_CONFIG": "${containerWorkspaceFolder}/config/duplo.yaml",
    "EDITOR": "code --wait"
  },
  "customizations": {
    "vscode": {
      "extensions": [],
      "settings": {}
    }
  }
}

Cloud-Specific Patterns

AWS Project

"features": {
  "ghcr.io/duplocloud/devcontainers/duploctl:latest": {},
  "ghcr.io/duplocloud/devcontainers/aws-cli:latest": {
    "jit": true,
    "jitAdmin": true
  }
},
"containerEnv": {
  "AWS_CONFIG_FILE": "${containerWorkspaceFolder}/config/aws",
  "AWS_DEFAULT_REGION": "us-east-1",
  "AWS_REGION": "us-east-1"
}

GCP Project

"features": {
  "ghcr.io/duplocloud/devcontainers/duploctl:latest": {},
  "ghcr.io/duplocloud/devcontainers/gcloud-cli:1": {}
},
"containerEnv": {
  "CLOUDSDK_CONFIG": "${containerWorkspaceFolder}/config/gcloud",
  "CLOUDSDK_PYTHON": "/usr/local/bin/python",
  "GOOGLE_APPLICATION_CREDENTIALS": "${containerWorkspaceFolder}/config/gcloud/application_default_credentials.json"
}

Kubernetes Access

"ghcr.io/duplocloud/devcontainers/kubernetes:1": {
  "jit": true,
  "jitAdmin": true,
  "plan": "nonprod01"
},
"containerEnv": {
  "KUBECONFIG": "${containerWorkspaceFolder}/config/kubeconfig.yaml"
}

Options:

• jit: Enable automatic JIT authentication
• jitAdmin: Use admin privileges (requires admin token)
• plan: DuploCloud infrastructure name

AI Tools

Choose based on team's AI provider preference:

Claude (Anthropic)

"ghcr.io/duplocloud/devcontainers/ai-claude:1": {
  "skills": "tf-module"
}

Skills installed to: ~/.claude/skills/

Codex (OpenAI)

"ghcr.io/duplocloud/devcontainers/ai-codex:1": {
  "skills": "tf-module"
},
"containerEnv": {
  "CODEX_HOME": "${containerWorkspaceFolder}/.codex"
}

Skills installed to: $CODEX_HOME/skills/

Gemini (Google)

"ghcr.io/duplocloud/devcontainers/ai-gemini:1": {
  "skills": "tf-module"
}

Skills installed to: ~/.gemini/skills/

GitHub Copilot

"ghcr.io/duplocloud/devcontainers/github:latest": {
  "installCopilot": true,
  "skills": "tf-module"
}

1Password SSH Integration

Required Local Environment Variables

These must be set on the host machine for 1Password to work:

| Variable | Purpose | Example | |----------|---------|--------| | OP_ACCOUNT | 1Password account domain | my.1password.com | | OP_VAULT_NAME | Vault containing SSH keys | Employee | | OP_SSH_SECRET | SSH key secret name in 1Password | GitHub SSH Key | | OP_AUTO_SSH | Enable auto SSH config | true | | USER_EMAIL | Email for 1Password account | you@company.com |

Feature Configuration

"ghcr.io/duplocloud/devcontainers/onepassword-cli:1": {
  "autoSsh": "${localEnv:OP_AUTO_SSH}",
  "sshSecretNames": "${localEnv:OP_SSH_SECRET}",
  "vault": "${localEnv:OP_VAULT_NAME}",
  "account": "${localEnv:OP_ACCOUNT}",
  "userEmail": "${localEnv:USER_EMAIL}"
}

SSH Secret Requirements in 1Password

Critical: For auto SSH config to work, your 1Password SSH secret needs custom fields:

| Field | Required | Description | Example | |-------|----------|-------------|--------| | host | Yes | Hostname for SSH | github.com | | username | Recommended | SSH username | git | | port | Optional | SSH port | 22 |

Without the host field, keys download but SSH config isn't created.

macOS SSH Agent Setup

Important for macOS users: You need to configure a Launch Agent to expose the 1Password SSH agent socket to devcontainers.

Follow: 1Password SSH Agent Compatibility

Verify SSH agent is working:

ssh-add -l

Debugging 1Password Issues

Common problems:

1. "No vault specified" error

   • Ensure OP_VAULT_NAME or vault option is set
   • Service accounts/Connect Server require vault specification

2. SSH keys not configured

   • Check SSH secret has host custom field in 1Password
   • Verify autoSsh is true (not string "true")

3. Repeated account setup on rebuild

   • Set XDG_CONFIG_HOME to workspace config folder
   • 1Password data persists in $XDG_CONFIG_HOME/op/

4. macOS SSH agent not forwarding

   • Configure Launch Agent per 1Password docs
   • Check SSH_AUTH_SOCK is set in container

5. Interactive login required every time

   • Set userEmail to skip email prompt
   • Use XDG_CONFIG_HOME for persistence
   • Consider Service Account token for automation

For detailed troubleshooting: Read the full feature README: https://raw.githubusercontent.com/duplocloud/devcontainers/refs/heads/main/src/onepassword-cli/README.md

Authentication Methods (checked in order)

1. Connect Server (OP_CONNECT_HOST + OP_CONNECT_TOKEN)
2. Service Account (OP_SERVICE_ACCOUNT_TOKEN)
3. Desktop App Agent (Linux only, ~/.1password/agent.sock)
4. Interactive Login

Git Configuration

"ghcr.io/duplocloud/devcontainers/git:1": {
  "userName": "${localEnv:GIT_USERNAME}",
  "userEmail": "${localEnv:GIT_EMAIL}",
  "signingKey": "${localEnv:GIT_SIGNING_KEY}"
}

Options:

• userName: Git user.name (fallback: GIT_USER env)
• userEmail: Git user.email (fallback: GIT_EMAIL env)
• signingKey: Path to signing key relative to ~/.ssh
• installGitKraken: Install GitKraken CLI

Included plugins:

• git-bump - Semantic version bumping (git bump -v patch)
• git-setenv - Export CI env vars (eval $(git setenv bitbucket))

Integration with 1Password for signed commits:

{
  "ghcr.io/duplocloud/devcontainers/onepassword-cli:1": {
    "autoSsh": true,
    "sshSecretNames": "GitHub SSH Key"
  },
  "ghcr.io/duplocloud/devcontainers/git:1": {
    "signingKey": "GitHub_SSH_Key.pub"
  }
}

OpenVPN Access

Note: Primarily useful for GitHub Codespaces. Can be disabled for local devcontainers.

"ghcr.io/duplocloud/devcontainers/openvpn:1": {
  "enabled": "${localEnv:DEVCONTAINER_VPN_ENABLED:-false}",
  "autoConnect": true
},
"runArgs": ["--device=/dev/net/tun"]

Options:

• enabled: Enable/disable feature (use localEnv to toggle)
• autoConnect: Auto-connect on container start (default: true)
• configDir: Custom config directory

Required: Must add --device=/dev/net/tun to runArgs.

direnv

"ghcr.io/duplocloud/devcontainers/direnv:1": {}

Installs direnv with DuploCloud-specific direnvrc at $HOME/direnv/direnvrc.

Terraform Projects

"ghcr.io/duplocloud/devcontainers/terraform:1": {},
"customizations": {
  "vscode": {
    "extensions": ["hashicorp.terraform"],
    "settings": {
      "[terraform]": {
        "editor.defaultFormatter": "hashicorp.terraform",
        "editor.formatOnSave": true
      }
    }
  }
}

Decision Flow

1. Read README.md for project context
2. Search workspace for cloud indicators (AWS/GCP)
3. Check for Terraform files
4. Check for Kubernetes references
5. Determine git provider
6. Add AI tools based on project complexity
7. Add 1Password if team uses it

Common Extensions by Stack

| Stack | Extensions | |-------|------------| | Python | ms-python.python | | Terraform | hashicorp.terraform | | Kubernetes | ms-kubernetes-tools.vscode-kubernetes-tools | | YAML | redhat.vscode-yaml | | GitHub | github.vscode-github-actions, GitHub.copilot-chat | | Database | cweijan.vscode-database-client2 | | Git | eamodio.gitlens | | AWS | amazonwebservices.aws-toolkit-vscode |

Extensions Auto-Installed by Features

| Feature | Extension | |---------|----------| | github | github.vscode-pull-request-github | | git | eamodio.gitlens | | ai-claude | anthropic.claude-code | | ai-codex | openai.chatgpt | | ai-gemini | Google.geminicodeassist | | aws-cli | amazonwebservices.aws-toolkit-vscode | | kubernetes | ms-kubernetes-tools.vscode-kubernetes-tools |

Learning More About Features

To learn about a specific feature's options, use web search to read its README:

https://raw.githubusercontent.com/duplocloud/devcontainers/refs/heads/main/src/<feature-name>/README.md

All feature README URLs:

• https://raw.githubusercontent.com/duplocloud/devcontainers/refs/heads/main/src/duploctl/README.md
• https://raw.githubusercontent.com/duplocloud/devcontainers/refs/heads/main/src/aws-cli/README.md
• https://raw.githubusercontent.com/duplocloud/devcontainers/refs/heads/main/src/gcloud-cli/README.md
• https://raw.githubusercontent.com/duplocloud/devcontainers/refs/heads/main/src/terraform/README.md
• https://raw.githubusercontent.com/duplocloud/devcontainers/refs/heads/main/src/kubernetes/README.md
• https://raw.githubusercontent.com/duplocloud/devcontainers/refs/heads/main/src/github/README.md
• https://raw.githubusercontent.com/duplocloud/devcontainers/refs/heads/main/src/git/README.md
• https://raw.githubusercontent.com/duplocloud/devcontainers/refs/heads/main/src/ai-claude/README.md
• https://raw.githubusercontent.com/duplocloud/devcontainers/refs/heads/main/src/ai-codex/README.md
• https://raw.githubusercontent.com/duplocloud/devcontainers/refs/heads/main/src/ai-gemini/README.md
• https://raw.githubusercontent.com/duplocloud/devcontainers/refs/heads/main/src/onepassword-cli/README.md
• https://raw.githubusercontent.com/duplocloud/devcontainers/refs/heads/main/src/direnv/README.md
• https://raw.githubusercontent.com/duplocloud/devcontainers/refs/heads/main/src/openvpn/README.md

Skill Resources

| Resource | Contents | |----------|----------| | references/features.md | Detailed feature options and configuration | | references/detection.md | Workspace search patterns for feature selection | | assets/templates/ | Ready-to-use template files |

Asset Templates

Use these templates as starting points - copy and customize:

| Template | Use Case | |----------|----------| | devcontainer.json.template | Minimal base template | | devcontainer-aws.json.template | AWS projects with JIT | | devcontainer-terraform.json.template | Terraform/IaC projects | | devcontainer-full.json.template | Full-featured with all tools | | init.sh | Initialize script (creates .env) | | post-start.sh | Post-start script placeholder |

Template placeholder: {{PROJECT_NAME}} - replace with devcontainer name