# CodeBuddy Code Dev Container

CodeBuddy Code Dev Container provides a pre-configured, secure development environment suitable for teams that need consistent and isolated workspaces. It seamlessly integrates with Visual Studio Code's Dev Containers extension and similar tools.


## Quick Start in Four Steps

1. **Install VS Code and the Remote - Containers extension**
2. **Create the `.devcontainer` directory and related files in your workspace following the configuration details below**
3. **Open the repository in VS Code**
4. **When prompted, click "Reopen in Container"** (or use Command Palette: Cmd+Shift+P → "Remote-Containers: Reopen in Container")

---

## Configuration Details

**Directory Structure**

```
your-project/
├── .devcontainer/
│   ├── devcontainer.json
│   ├── Dockerfile
│   └── init-firewall.sh
└── ...
```

The Dev Container setup consists of **three main components**:

---

### 🚀 Installing CodeBuddy Code (Recommended Approach)

#### Option 1: Using Dev Containers Feature (Recommended)

**Dev Containers Feature** is the **recommended way** to install CodeBuddy Code in a Dev Container. It provides automatic version management, configuration consistency with other features, simplified maintenance, and more.

**Advantages:**
- ✅ **Automatic version management** - Easily upgrade to the latest version or pin to a specific version
- ✅ **Configuration consistency** - Uses the same configuration approach as other Dev Containers features
- ✅ **Simplified maintenance** - No need to manage complex installation logic in Dockerfile
- ✅ **Team sharing** - Easy to standardize configuration across teams

**Configuration Method:**

Add configuration to the `features` field in `devcontainer.json`:

```json
{
    "name": "CodeBuddy Code Sandbox",
    "features": {
        "ghcr.io/devcontainers-contrib/features/codebuddy-code:1": {
            "version": "latest"
        }
    },
    // ... other configurations
}
```

**Pin to Specific Version:**

```json
{
    "features": {
        "ghcr.io/devcontainers-contrib/features/codebuddy-code:1": {
            "version": "2.16.0"
        }
    }
}
```

**Use Default Latest Version:**

```json
{
    "features": {
        "ghcr.io/devcontainers-contrib/features/codebuddy-code:1": {}
    }
}
```

#### Option 2: Manual Installation in Dockerfile

If you need more control or have special scenarios, you can manually install in the Dockerfile. See the **Dockerfile** section below for details.

---

### 1. devcontainer.json
Controls container settings, manages extensions, and configures volume mounts.

**Complete Example with Dev Containers Feature:**

```json
{
    "name": "CodeBuddy Code Sandbox",
    "build": {
        "dockerfile": "Dockerfile",
        "args": {
            "TZ": "${localEnv:TZ:America/Los_Angeles}",
            "GIT_DELTA_VERSION": "0.18.2",
            "ZSH_IN_DOCKER_VERSION": "1.2.0"
        }
    },
    "features": {
        "ghcr.io/devcontainers-contrib/features/codebuddy-code:1": {
            "version": "latest"
        }
    },
    "runArgs": [
        "--cap-add=NET_ADMIN",
        "--cap-add=NET_RAW"
    ],
    "customizations": {
        "vscode": {
            "extensions": [
                "dbaeumer.vscode-eslint",
                "esbenp.prettier-vscode",
                "eamodio.gitlens"
            ],
            "settings": {
                "editor.formatOnSave": true,
                "editor.defaultFormatter": "esbenp.prettier-vscode",
                "editor.codeActionsOnSave": {
                    "source.fixAll.eslint": "explicit"
                },
                "terminal.integrated.defaultProfile.linux": "zsh",
                "terminal.integrated.profiles.linux": {
                    "bash": {
                        "path": "bash",
                        "icon": "terminal-bash"
                    },
                    "zsh": {
                        "path": "zsh"
                    }
                }
            }
        }
    },
    "remoteUser": "node",
    "mounts": [
        "source=codebuddy-code-bashhistory-${devcontainerId},target=/commandhistory,type=volume",
        "source=codebuddy-code-config-${devcontainerId},target=/home/node/.codebuddy,type=volume"
    ],
    "containerEnv": {
        "NODE_OPTIONS": "--max-old-space-size=4096",
        "CODEBUDDY_CONFIG_DIR": "/home/node/.codebuddy",
        "POWERLEVEL9K_DISABLE_GITSTATUS": "true"
    },
    "workspaceMount": "source=${localWorkspaceFolder},target=/workspace,type=bind,consistency=delegated",
    "workspaceFolder": "/workspace",
    "postStartCommand": "sudo /usr/local/bin/init-firewall.sh",
    "waitFor": "postStartCommand"
}
```

**Key Configuration Notes:**
- `features` - Declares the use of CodeBuddy Code Dev Containers Feature, supports version management
- `version: "latest"` - Uses the latest version (can be replaced with a specific version like "2.16.0")
- Note: When using the Feature approach, no `CODEBUDDY_CODE_VERSION` parameter is needed in the Dockerfile

### 2. Dockerfile
Defines the container image and specifies the tools to install.

#### Simplified Dockerfile When Using Feature

If using the Dev Containers Feature above to install CodeBuddy Code, the Dockerfile can be more concise (no need for `CODEBUDDY_CODE_VERSION` parameter and manual installation commands):

> If you choose to use the Dev Containers Feature approach (recommended), you can refer to the "Simplified Dockerfile" below. If you need to manually install in the Dockerfile, refer to the "Complete Dockerfile".

**Simplified Dockerfile (Recommended with Feature):**

```dockerfile
FROM node:20

ARG TZ
ENV TZ="$TZ"

# Install basic development tools and iptables/ipset
RUN apt-get update && apt-get install -y --no-install-recommends \
  less \
  git \
  procps \
  sudo \
  fzf \
  zsh \
  man-db \
  unzip \
  gnupg2 \
  gh \
  iptables \
  ipset \
  iproute2 \
  dnsutils \
  aggregate \
  jq \
  nano \
  vim \
  && apt-get clean && rm -rf /var/lib/apt/lists/*

# Ensure default node user has access to /usr/local/share
RUN mkdir -p /usr/local/share/npm-global && \
  chown -R node:node /usr/local/share

ARG USERNAME=node

# Persist bash history.
RUN SNIPPET="export PROMPT_COMMAND='history -a' && export HISTFILE=/commandhistory/.bash_history" \
  && mkdir /commandhistory \
  && touch /commandhistory/.bash_history \
  && chown -R $USERNAME /commandhistory

# Set `DEVCONTAINER` environment variable to help with orientation
ENV DEVCONTAINER=true

# Create workspace and config directories and set permissions
RUN mkdir -p /workspace /home/node/.codebuddy && \
  chown -R node:node /workspace /home/node/.codebuddy

WORKDIR /workspace

ARG GIT_DELTA_VERSION=0.18.2
RUN ARCH=$(dpkg --print-architecture) && \
  wget "https://github.com/dandavison/delta/releases/download/${GIT_DELTA_VERSION}/git-delta_${GIT_DELTA_VERSION}_${ARCH}.deb" && \
  sudo dpkg -i "git-delta_${GIT_DELTA_VERSION}_${ARCH}.deb" && \
  rm "git-delta_${GIT_DELTA_VERSION}_${ARCH}.deb"

# Set up non-root user
USER node

# Install global packages
ENV NPM_CONFIG_PREFIX=/usr/local/share/npm-global
ENV PATH=$PATH:/usr/local/share/npm-global/bin

# Set the default shell to zsh rather than sh
ENV SHELL=/bin/zsh

# Set the default editor and visual
ENV EDITOR=nano
ENV VISUAL=nano

# Default powerline10k theme
ARG ZSH_IN_DOCKER_VERSION=1.2.0
RUN sh -c "$(wget -O- https://github.com/deluan/zsh-in-docker/releases/download/v${ZSH_IN_DOCKER_VERSION}/zsh-in-docker.sh)" -- \
  -p git \
  -p fzf \
  -a "source /usr/share/doc/fzf/examples/key-bindings.zsh" \
  -a "source /usr/share/doc/fzf/examples/completion.zsh" \
  -a "export PROMPT_COMMAND='history -a' && export HISTFILE=/commandhistory/.bash_history" \
  -x

# CodeBuddy Code will be installed via Dev Containers Feature

# Copy and set up firewall script
COPY init-firewall.sh /usr/local/bin/
USER root
RUN chmod +x /usr/local/bin/init-firewall.sh && \
  echo "node ALL=(root) NOPASSWD: /usr/local/bin/init-firewall.sh" > /etc/sudoers.d/node-firewall && \
  chmod 0440 /etc/sudoers.d/node-firewall
USER node
```

#### Complete Dockerfile for Manual Installation

If you need full control over the installation process, you can manually install CodeBuddy Code in the Dockerfile (this approach does not use Dev Containers Feature):

```dockerfile
FROM node:20

ARG TZ
ENV TZ="$TZ"

ARG CODEBUDDY_CODE_VERSION=latest

# Install basic development tools and iptables/ipset
RUN apt-get update && apt-get install -y --no-install-recommends \
  less \
  git \
  procps \
  sudo \
  fzf \
  zsh \
  man-db \
  unzip \
  gnupg2 \
  gh \
  iptables \
  ipset \
  iproute2 \
  dnsutils \
  aggregate \
  jq \
  nano \
  vim \
  && apt-get clean && rm -rf /var/lib/apt/lists/*

# Ensure default node user has access to /usr/local/share
RUN mkdir -p /usr/local/share/npm-global && \
  chown -R node:node /usr/local/share

ARG USERNAME=node

# Persist bash history.
RUN SNIPPET="export PROMPT_COMMAND='history -a' && export HISTFILE=/commandhistory/.bash_history" \
  && mkdir /commandhistory \
  && touch /commandhistory/.bash_history \
  && chown -R $USERNAME /commandhistory

# Set `DEVCONTAINER` environment variable to help with orientation
ENV DEVCONTAINER=true

# Create workspace and config directories and set permissions
RUN mkdir -p /workspace /home/node/.codebuddy && \
  chown -R node:node /workspace /home/node/.codebuddy

WORKDIR /workspace

ARG GIT_DELTA_VERSION=0.18.2
RUN ARCH=$(dpkg --print-architecture) && \
  wget "https://github.com/dandavison/delta/releases/download/${GIT_DELTA_VERSION}/git-delta_${GIT_DELTA_VERSION}_${ARCH}.deb" && \
  sudo dpkg -i "git-delta_${GIT_DELTA_VERSION}_${ARCH}.deb" && \
  rm "git-delta_${GIT_DELTA_VERSION}_${ARCH}.deb"

# Set up non-root user
USER node

# Install global packages
ENV NPM_CONFIG_PREFIX=/usr/local/share/npm-global
ENV PATH=$PATH:/usr/local/share/npm-global/bin

# Set the default shell to zsh rather than sh
ENV SHELL=/bin/zsh

# Set the default editor and visual
ENV EDITOR=nano
ENV VISUAL=nano

# Default powerline10k theme
ARG ZSH_IN_DOCKER_VERSION=1.2.0
RUN sh -c "$(wget -O- https://github.com/deluan/zsh-in-docker/releases/download/v${ZSH_IN_DOCKER_VERSION}/zsh-in-docker.sh)" -- \
  -p git \
  -p fzf \
  -a "source /usr/share/doc/fzf/examples/key-bindings.zsh" \
  -a "source /usr/share/doc/fzf/examples/completion.zsh" \
  -a "export PROMPT_COMMAND='history -a' && export HISTFILE=/commandhistory/.bash_history" \
  -x

# Install CodeBuddy Code (manual installation method - only if not using Dev Containers Feature)
RUN npm install -g @tencent-ai/codebuddy-code@${CODEBUDDY_CODE_VERSION}

# Copy and set up firewall script
COPY init-firewall.sh /usr/local/bin/
USER root
RUN chmod +x /usr/local/bin/init-firewall.sh && \
  echo "node ALL=(root) NOPASSWD: /usr/local/bin/init-firewall.sh" > /etc/sudoers.d/node-firewall && \
  chmod 0440 /etc/sudoers.d/node-firewall
USER node
```

> **Note:** If using this approach, the `build.args` in devcontainer.json needs to include the `"CODEBUDDY_CODE_VERSION"` parameter, and the `features` field should not include the CodeBuddy Code Feature.

### 3. init-firewall.sh
Establishes network security rules.

```bash
#!/bin/bash
set -euo pipefail  # Exit on error, undefined vars, and pipeline failures
IFS=$'\n\t'       # Stricter word splitting

# 1. Extract Docker DNS info BEFORE any flushing
DOCKER_DNS_RULES=$(iptables-save -t nat | grep "127\.0\.0\.11" || true)

# Flush existing rules and delete existing ipsets
iptables -F
iptables -X
iptables -t nat -F
iptables -t nat -X
iptables -t mangle -F
iptables -t mangle -X
ipset destroy allowed-domains 2>/dev/null || true

# 2. Selectively restore ONLY internal Docker DNS resolution
if [ -n "$DOCKER_DNS_RULES" ]; then
    echo "Restoring Docker DNS rules..."
    iptables -t nat -N DOCKER_OUTPUT 2>/dev/null || true
    iptables -t nat -N DOCKER_POSTROUTING 2>/dev/null || true
    echo "$DOCKER_DNS_RULES" | xargs -L 1 iptables -t nat
else
    echo "No Docker DNS rules to restore"
fi

# First allow DNS and localhost before any restrictions
# Allow outbound DNS
iptables -A OUTPUT -p udp --dport 53 -j ACCEPT
# Allow inbound DNS responses
iptables -A INPUT -p udp --sport 53 -j ACCEPT
# Allow outbound SSH
iptables -A OUTPUT -p tcp --dport 22 -j ACCEPT
# Allow inbound SSH responses
iptables -A INPUT -p tcp --sport 22 -m state --state ESTABLISHED -j ACCEPT
# Allow localhost
iptables -A INPUT -i lo -j ACCEPT
iptables -A OUTPUT -o lo -j ACCEPT

# Create ipset with CIDR support
ipset create allowed-domains hash:net

# Fetch GitHub meta information and aggregate + add their IP ranges
echo "Fetching GitHub IP ranges..."
gh_ranges=$(curl -s https://api.github.com/meta)
if [ -z "$gh_ranges" ]; then
    echo "ERROR: Failed to fetch GitHub IP ranges"
    exit 1
fi

if ! echo "$gh_ranges" | jq -e '.web and .api and .git' >/dev/null; then
    echo "ERROR: GitHub API response missing required fields"
    exit 1
fi

echo "Processing GitHub IPs..."
while read -r cidr; do
    if [[ ! "$cidr" =~ ^[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}/[0-9]{1,2}$ ]]; then
        echo "ERROR: Invalid CIDR range from GitHub meta: $cidr"
        exit 1
    fi
    echo "Adding GitHub range $cidr"
    ipset add allowed-domains "$cidr"
done < <(echo "$gh_ranges" | jq -r '(.web + .api + .git)[]' | aggregate -q)

# Resolve and add other allowed domains
for domain in \
    "registry.npmjs.org" \
    "copilot.tencent.com" \
    "sentry.io" \
    "marketplace.visualstudio.com" \
    "vscode.blob.core.windows.net" \
    "update.code.visualstudio.com"; do
    echo "Resolving $domain..."
    ips=$(dig +noall +answer A "$domain" | awk '$4 == "A" {print $5}')
    if [ -z "$ips" ]; then
        echo "ERROR: Failed to resolve $domain"
        exit 1
    fi
    
    while read -r ip; do
        if [[ ! "$ip" =~ ^[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}$ ]]; then
            echo "ERROR: Invalid IP from DNS for $domain: $ip"
            exit 1
        fi
        echo "Adding $ip for $domain"
        ipset add allowed-domains "$ip"
    done < <(echo "$ips")
done

# Get host IP from default route
HOST_IP=$(ip route | grep default | cut -d" " -f3)
if [ -z "$HOST_IP" ]; then
    echo "ERROR: Failed to detect host IP"
    exit 1
fi

HOST_NETWORK=$(echo "$HOST_IP" | sed "s/\.[0-9]*$/.0\/24/")
echo "Host network detected as: $HOST_NETWORK"

# Set up remaining iptables rules
iptables -A INPUT -s "$HOST_NETWORK" -j ACCEPT
iptables -A OUTPUT -d "$HOST_NETWORK" -j ACCEPT

# Set default policies to DROP first
iptables -P INPUT DROP
iptables -P FORWARD DROP
iptables -P OUTPUT DROP

# First allow established connections for already approved traffic
iptables -A INPUT -m state --state ESTABLISHED,RELATED -j ACCEPT
iptables -A OUTPUT -m state --state ESTABLISHED,RELATED -j ACCEPT

# Then allow only specific outbound traffic to allowed domains
iptables -A OUTPUT -m set --match-set allowed-domains dst -j ACCEPT

# Explicitly REJECT all other outbound traffic for immediate feedback
iptables -A OUTPUT -j REJECT --reject-with icmp-admin-prohibited

echo "Firewall configuration complete"
echo "Verifying firewall rules..."
if curl --connect-timeout 5 https://example.com >/dev/null 2>&1; then
    echo "ERROR: Firewall verification failed - was able to reach https://example.com"
    exit 1
else
    echo "Firewall verification passed - unable to reach https://example.com as expected"
fi

# Verify GitHub API access
if ! curl --connect-timeout 5 https://api.github.com/zen >/dev/null 2>&1; then
    echo "ERROR: Firewall verification failed - unable to reach https://api.github.com"
    exit 1
else
    echo "Firewall verification passed - able to reach https://api.github.com as expected"
fi
```

---

## Security Features

The container implements **multi-layer security protection**:

- **Precise Access Control**: Restricts outbound connections to whitelisted domains (npm registry, GitHub, CodeBuddy API, etc.)
- **Allowed Outbound Connections**: Firewall permits outbound DNS and SSH connections
- **Default Deny Policy**: Blocks all other external network access
- **Startup Verification**: Validates firewall rules during container initialization
- **Isolation**: Creates a secure development environment separated from the host system

### Important Security Note
> While the dev container provides substantial protection, no system is completely immune to all attacks. When running with `-y` (or `--dangerously-skip-permissions`), the dev container cannot prevent malicious projects from stealing anything accessible within the container, including CodeBuddy Code credentials. **We recommend using the dev container only with trusted repositories.** Always maintain good security practices and monitor CodeBuddy's activity.

### Unattended Operation
The container's enhanced security measures (isolation and firewall rules) allow you to run `codebuddy -y` (or `codebuddy --dangerously-skip-permissions`) to bypass permission prompts for unattended operation.

---

## Customization Options

The dev container configuration is designed to be flexible and can be adjusted to your needs:

- Add or remove VS Code extensions based on your workflow
- Adjust resource allocation for different hardware environments
- Modify network access permissions
- Customize shell configuration and development tools

---

## Use Cases

### 1. Secure Client Project Development
Use dev containers to isolate different client projects, ensuring code and credentials never mix.

### 2. Rapid Team Onboarding
New team members can get a fully configured development environment in minutes, with all necessary tools and settings pre-installed.

### 3. Consistent CI/CD Environment
Mirror your dev container configuration in CI/CD pipelines to ensure development and production environments match.

---

## Related Resources

- [VS Code Dev Containers Documentation](https://code.visualstudio.com/docs/devcontainers/containers)
- [Bash Sandbox](./bash-sandboxing.md)
- [Settings Configuration](./settings.md)
- [GitLab CI/CD Integration](./gitlab-ci-cd.md)
- 📖 [Official Dev Containers Docs](https://containers.dev/)
- 🔗 [devcontainers-contrib/features](https://github.com/devcontainers-contrib/features)
