feat(installer-agent): Add non-root devcontainer user detection and permission handling

[WilliamBerryiii]

Summary

The hve-core-installer.agent.md needs to detect when running in a devcontainer with a non-root user (e.g., vscode) and modify clone/ownership commands accordingly to prevent permission issues.

Problem Statement

When a devcontainer is configured with "remoteUser": "vscode" (or any non-root user), the current installer agent's Method 4 (postCreateCommand) commands fail or create files inaccessible to the non-root user because:

1. /workspaces/ directory ownership: In devcontainers, the /workspaces/ directory and its contents may be owned by root while the container runs as a non-root user
2. git clone permission failures: The non-root user cannot clone directly to root-owned directories
3. Post-clone access issues: Even if clone succeeds, created files may be inaccessible to the non-root user for reading/writing

Current Behavior (Fails)

{
  "remoteUser": "vscode",
  "postCreateCommand": {
    "clone-hve-core": "if [ ! -d /workspaces/hve-core ]; then git clone --depth 1 https://github.com/microsoft/hve-core.git /workspaces/hve-core && echo '✅ HVE-Core cloned'; else echo '✅ HVE-Core present'; fi"
  }
}

Error scenarios:

• fatal: could not create work tree dir '/workspaces/hve-core': Permission denied
• Files cloned by root are not writable by vscode user
• Lifecycle scripts fail silently due to permission issues

Expected Behavior (Proposed)

{
  "remoteUser": "vscode",
  "postCreateCommand": {
    "clone-hve-core": "if [ ! -d ${containerWorkspaceFolder}/../hve-core ]; then sudo git clone --depth 1 https://github.com/microsoft/hve-core.git ${containerWorkspaceFolder}/../hve-core && sudo chown -R vscode:vscode ${containerWorkspaceFolder}/../hve-core && echo '✅ HVE-Core cloned'; else echo '✅ HVE-Core present'; fi"
  }
}

Technical Background

Non-Root User Detection

According to the devcontainer spec and VS Code documentation:

• remoteUser: Specifies the user VS Code and sub-processes (terminals, tasks, debugging) run as
• containerUser: Specifies the user all container processes run as
• Base images like mcr.microsoft.com/devcontainers/base:ubuntu include a pre-configured vscode user (UID 1000)

Permission Model by Platform

Platform	Behavior
Docker Desktop (Mac)	Mounted files act as owned by container user; local ops use host permissions
Docker Desktop (Windows)	Files appear owned by root but are accessible; all files are executable
Docker CE/EE (Linux)	Exact permission mapping - UID/GID must match or sudo is required
GitHub Codespaces	Non-root user (codespace) is default; /workspaces/ may be root-owned

Detection Logic

The installer agent should detect non-root scenarios using:

# Shell detection
if [ "$(id -u)" != "0" ]; then
  IS_NON_ROOT_USER="true"
  CURRENT_USER="$(whoami)"
fi

# Check if running in devcontainer with remoteUser
if [ -n "$REMOTE_CONTAINERS_IPC" ] || [ -f "/.dockerenv" ]; then
  IS_DEVCONTAINER="true"
fi

Proposed Changes

1. Add Non-Root User Detection Phase

Add to Phase 2 (Environment Discovery) in hve-core-installer.agent.md:

### Non-Root User Detection

**Detection Script (Bash):**
```bash
# Detect if running as non-root user in a devcontainer
IS_NON_ROOT=false
CURRENT_USER="$(whoami)"
CURRENT_UID="$(id -u)"

if [ "$CURRENT_UID" != "0" ]; then
  IS_NON_ROOT=true
fi

# Detect if /workspaces is root-owned
WORKSPACES_OWNER="$(stat -c '%U' /workspaces 2>/dev/null || echo 'N/A')"
NEEDS_SUDO=false

if [ "$IS_NON_ROOT" = "true" ] && [ "$WORKSPACES_OWNER" = "root" ]; then
  NEEDS_SUDO=true
fi

### 2. Update Method 4 postCreateCommand Examples

Provide two variants:

**Standard (root user or pre-configured permissions):**
```jsonc
"postCreateCommand": {
  "clone-hve-core": "[ -d /workspaces/hve-core ] || git clone --depth 1 https://github.com/microsoft/hve-core.git /workspaces/hve-core"
}

Non-root user aware:

"postCreateCommand": {
  "clone-hve-core": "if [ ! -d ${containerWorkspaceFolder}/../hve-core ]; then sudo git clone --depth 1 https://github.com/microsoft/hve-core.git ${containerWorkspaceFolder}/../hve-core && sudo chown -R $(whoami):$(whoami) ${containerWorkspaceFolder}/../hve-core && echo '✅ HVE-Core cloned'; else echo '✅ HVE-Core present'; fi"
}

3. Add Decision Matrix Branch

Update the decision matrix to include non-root user detection:

Question	Yes →	No →
Running as non-root user (id -u ≠ 0)?	Check /workspaces ownership	Use standard commands
Is /workspaces root-owned?	Use sudo + chown pattern	Use standard commands

4. Document Known Scenarios

Add a troubleshooting section covering:

• Permission denied during clone
• Files not writable after clone
• How to detect if sudo is available
• Fallback strategies if sudo is unavailable

Acceptance Criteria

• Phase 2 includes non-root user detection script
• Method 4 provides both standard and non-root-aware variants
• Decision matrix includes non-root user branch
• All Method 4 examples use ${containerWorkspaceFolder} variable where appropriate
• Troubleshooting section documents permission issues and solutions
• Detection logic works for:
  • GitHub Codespaces (codespace user)
  • Local devcontainers (vscode user)
  • Custom devcontainer images with non-root users

Related Documentation

• VS Code: Add a non-root user to a container
• Dev Container Spec: remoteUser
• Dev Container Spec: Variables in devcontainer.json

Affected Files

• .github/agents/hve-core-installer.agent.md (primary)
• docs/getting-started/methods/codespaces.md (documentation update)

Labels

enhancement, documentation, devcontainer

[cicorias]

there are two other scenarios that I use extensively might want to consider; both are as normal users/non root

1. running via SSH into a normal Linux box (remote SSH) - just FYI doesn't impact this issue BUT -->
2. running a remote Devcontainer via SSH on a remote machine (Linux) - yes, this works great btw -- and it does suffer from "dont add or commit in git while IN the container

The jist is ensuring we pickup the $USER ON the host and -- for that DevContainer

don't ask why...

@WilliamBerryiii

I've used this

FROM ubuntu:22.04

# USERNAME will be provided by devcontainer.json
ARG USERNAME=vscode

RUN apt-get update && apt-get install -y sudo \
    && groupadd --gid 1000 ${USERNAME} \
    && useradd --uid 1000 --gid 1000 -m ${USERNAME} \
    && echo "${USERNAME} ALL=(root) NOPASSWD:ALL" > /etc/sudoers.d/${USERNAME} \
    && chmod 0440 /etc/sudoers.d/${USERNAME}

USER ${USERNAME}
WORKDIR /home/${USERNAME}

devcontainer.json

{
  "name": "remote-devcontainer-dynamic-user",
  "build": {
    "dockerfile": "Dockerfile",
    "args": {
      // On Remote-SSH, this resolves to the SSH user on the remote host
      "USERNAME": "${localEnv:USER}"
    }
  },

  "containerUser": "${localEnv:USER}",
  "remoteUser": "${localEnv:USER}",

  // Sync UID/GID of that user with the host user on Linux
  "updateRemoteUserUID": true
}

alt devcontainer.json

{
  "name": "SSH User Dev Container",
  
  "build": {
    "dockerfile": "Dockerfile",
    "args": {
      "USERNAME": "${localEnv:USER}" 
    }
  },
  "remoteUser": "${containerEnv:USERNAME}",

 // This ensures chown matches SSH user.
  "containerEnv": {
      "USERNAME": "${localEnv:USER}"
  },

  // Optional
  "mounts": [
      "source=/var/run/docker.sock,target=/var/run/docker.sock,type=bind",
      "source=${localEnv:SSH_AUTH_SOCK},target=/tmp/ssh-agent,type=bind"
  ],
  "init": true,
  "settings": {}
}

compose

version: "3.8"
services:
  app:
    build:
      context: .
      dockerfile: .devcontainer/Dockerfile
      args:
        USERNAME: ${USER}    # SSH user on the remote host
    user: "${USER}"          # run processes as that user
    volumes:
      - ..:/workspace
    working_dir: /workspace

{
  "name": "remote-compose-devcontainer",
  "dockerComposeFile": "docker-compose.yml",
  "service": "app",

  "remoteUser": "${localEnv:USER}",
  "updateRemoteUserUID": true
}