Mounted Directory Installation

Mounted Directory installation shares a single HVE Core clone across multiple devcontainer projects by mounting a peer directory from the host filesystem. This is an advanced method requiring container rebuilds.

When to Use This Method

✅ Use this when:

• You have multiple devcontainer projects needing HVE Core
• You want a single shared installation (one update applies everywhere)
• You're comfortable with devcontainer configuration
• You're using local devcontainers only (not Codespaces)

❌ Consider alternatives when:

• You use Codespaces → GitHub Codespaces (mounts don't work)
• You want simpler setup → Git-Ignored Folder
• Your team needs version control → Submodule
• You need paths that work everywhere → Multi-Root Workspace

⚠️ Important Limitations

This method does NOT work in GitHub Codespaces. Codespaces doesn't support ${localWorkspaceFolder} or bind mounts to host filesystem.

Requires container rebuild. After adding the mount, you must rebuild the devcontainer before HVE Core becomes accessible.

How It Works

HVE Core is cloned on your host machine as a sibling to your project. The devcontainer mounts this directory into the container at /workspaces/hve-core.

Host File System:
projects/
├── my-project/                    # Your project (workspace)
│   └── .devcontainer/
│       └── devcontainer.json      # Contains mount configuration
│
└── hve-core/                      # Peer directory on HOST
    └── .github/
        ├── agents/
        ├── prompts/
        └── instructions/

Inside Container (after rebuild):
/workspaces/
├── my-project/                    # Mounted workspace
└── hve-core/                      # Mounted peer directory

Installation Workflow

This method requires a multi-phase workflow:

┌─────────────────────────────────────────────────────────────┐
│ Phase 1: Clone HVE Core on HOST                             │
│          ↓                                                  │
│ Phase 2: Add mount to devcontainer.json                     │
│          ↓                                                  │
│ Phase 3: Rebuild container (1-3 minutes)                    │
│          ↓                                                  │
│ Phase 4: Configure VS Code settings                         │
│          ↓                                                  │
│ Phase 5: Validate installation                              │
└─────────────────────────────────────────────────────────────┘

Quick Start

Install the VS Code extension for the fastest setup. For guided setup with installation method selection and MCP configuration, install the HVE Core Installer extension and ask any agent "help me customize hve-core installation". Use the manual steps below for direct configuration.

Manual Setup

Phase 1: Clone HVE Core on Host

Important: Clone on your host machine, not inside the container.

Open a terminal on your host (not in VS Code's container terminal):

# Navigate to parent of your project
cd /path/to/projects

# Clone HVE Core as a sibling
git clone https://github.com/microsoft/hve-core.git

Verify structure:

projects/
├── my-project/
└── hve-core/        # ← Must exist on HOST before rebuild

Phase 2: Add Mount to devcontainer.json

Update .devcontainer/devcontainer.json:

{
  // ... existing configuration ...
  
  "mounts": [
    "source=${localWorkspaceFolder}/../hve-core,target=/workspaces/hve-core,type=bind,readonly=true,consistency=cached"
  ]
}

Alternative object format

{
  "mounts": [
    {
      "type": "bind",
      "source": "${localWorkspaceFolder}/../hve-core",
      "target": "/workspaces/hve-core"
    }
  ]
}

Phase 3: Rebuild Container

⚠️ Container rebuild is required to apply the mount.

1. Press Ctrl+Shift+P (or Cmd+Shift+P on macOS)
2. Type "Dev Containers: Rebuild Container"
3. Press Enter and wait for rebuild (1-3 minutes)

What happens during rebuild

• Current container stops
• New container builds with mount configuration
• Extensions reinstall
• Lifecycle scripts re-run

Phase 4: Configure VS Code Settings

After rebuild, update .vscode/settings.json:

{
  "chat.agentFilesLocations": {
    "/workspaces/hve-core/.github/agents/ado": true,
    "/workspaces/hve-core/.github/agents/data-science": true,
    "/workspaces/hve-core/.github/agents/design-thinking": true,
    "/workspaces/hve-core/.github/agents/github": true,
    "/workspaces/hve-core/.github/agents/project-planning": true,
    "/workspaces/hve-core/.github/agents/hve-core": true,
    "/workspaces/hve-core/.github/agents/hve-core/subagents": true,
    "/workspaces/hve-core/.github/agents/security": true
  },
  "chat.promptFilesLocations": {
    "/workspaces/hve-core/.github/prompts/ado": true,
    "/workspaces/hve-core/.github/prompts/design-thinking": true,
    "/workspaces/hve-core/.github/prompts/github": true,
    "/workspaces/hve-core/.github/prompts/hve-core": true,
    "/workspaces/hve-core/.github/prompts/security": true
  },
  "chat.instructionsFilesLocations": {
    "/workspaces/hve-core/.github/instructions/ado": true,
    "/workspaces/hve-core/.github/instructions/coding-standards": true,
    "/workspaces/hve-core/.github/instructions/design-thinking": true,
    "/workspaces/hve-core/.github/instructions/github": true,
    "/workspaces/hve-core/.github/instructions/hve-core": true,
    "/workspaces/hve-core/.github/instructions/shared": true
  },
  "chat.agentSkillsLocations": {
    "/workspaces/hve-core/.github/skills": true,
    "/workspaces/hve-core/.github/skills/shared": true
  }
}

Or add to devcontainer.json (recommended for team sharing):

{
  "customizations": {
    "vscode": {
      "settings": {
        "chat.agentFilesLocations": {
          "/workspaces/hve-core/.github/agents/ado": true,
          "/workspaces/hve-core/.github/agents/data-science": true,
          "/workspaces/hve-core/.github/agents/design-thinking": true,
          "/workspaces/hve-core/.github/agents/github": true,
          "/workspaces/hve-core/.github/agents/project-planning": true,
          "/workspaces/hve-core/.github/agents/hve-core": true,
          "/workspaces/hve-core/.github/agents/hve-core/subagents": true,
          "/workspaces/hve-core/.github/agents/security": true
        },
        "chat.promptFilesLocations": {
          "/workspaces/hve-core/.github/prompts/ado": true,
          "/workspaces/hve-core/.github/prompts/design-thinking": true,
          "/workspaces/hve-core/.github/prompts/github": true,
          "/workspaces/hve-core/.github/prompts/hve-core": true,
          "/workspaces/hve-core/.github/prompts/security": true
        },
        "chat.instructionsFilesLocations": {
          "/workspaces/hve-core/.github/instructions/ado": true,
          "/workspaces/hve-core/.github/instructions/coding-standards": true,
          "/workspaces/hve-core/.github/instructions/design-thinking": true,
          "/workspaces/hve-core/.github/instructions/github": true,
          "/workspaces/hve-core/.github/instructions/hve-core": true,
          "/workspaces/hve-core/.github/instructions/shared": true
        },
        "chat.agentSkillsLocations": {
          "/workspaces/hve-core/.github/skills": true,
          "/workspaces/hve-core/.github/skills/shared": true
        }
      }
    }
  }
}

Phase 5: Validate Installation

1. Open GitHub Copilot Chat (Ctrl+Alt+I)
2. Click the agent picker dropdown
3. Verify HVE Core agents appear (task-planner, task-researcher, prompt-builder)

Verify mount from container terminal

ls /workspaces/hve-core/.github/agents

Complete Devcontainer Example

{
  "name": "My Project with Mounted HVE Core",
  "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
  
  "mounts": [
    "source=${localWorkspaceFolder}/../hve-core,target=/workspaces/hve-core,type=bind,readonly=true,consistency=cached"
  ],
  
  "customizations": {
    "vscode": {
      "settings": {
        "chat.agentFilesLocations": {
          "/workspaces/hve-core/.github/agents/ado": true,
          "/workspaces/hve-core/.github/agents/data-science": true,
          "/workspaces/hve-core/.github/agents/design-thinking": true,
          "/workspaces/hve-core/.github/agents/github": true,
          "/workspaces/hve-core/.github/agents/project-planning": true,
          "/workspaces/hve-core/.github/agents/hve-core": true,
          "/workspaces/hve-core/.github/agents/hve-core/subagents": true,
          "/workspaces/hve-core/.github/agents/security": true
        },
        "chat.promptFilesLocations": {
          "/workspaces/hve-core/.github/prompts/ado": true,
          "/workspaces/hve-core/.github/prompts/design-thinking": true,
          "/workspaces/hve-core/.github/prompts/github": true,
          "/workspaces/hve-core/.github/prompts/hve-core": true,
          "/workspaces/hve-core/.github/prompts/security": true
        },
        "chat.instructionsFilesLocations": {
          "/workspaces/hve-core/.github/instructions/ado": true,
          "/workspaces/hve-core/.github/instructions/coding-standards": true,
          "/workspaces/hve-core/.github/instructions/design-thinking": true,
          "/workspaces/hve-core/.github/instructions/github": true,
          "/workspaces/hve-core/.github/instructions/hve-core": true,
          "/workspaces/hve-core/.github/instructions/shared": true
        },
        "chat.agentSkillsLocations": {
          "/workspaces/hve-core/.github/skills": true,
          "/workspaces/hve-core/.github/skills/shared": true
        }
      }
    }
  }
}

Updating HVE Core

Update on your host machine:

cd /path/to/projects/hve-core
git pull

Changes are immediately available in all containers using the mount. No rebuild required for content updates.

Troubleshooting

Mount Point Empty After Rebuild

Cause: HVE Core wasn't cloned on the host, or was cloned in the wrong location.

Fix

1. Exit the container
2. Clone HVE Core on your host machine (see Phase 1)
3. Verify the path matches the mount source
4. Rebuild the container

Check from host terminal

# On host, not in container
ls /path/to/projects/hve-core/.github

Container Fails to Start

Cause: Mount source path doesn't exist.

Fix

1. Check devcontainer.json mount path
2. Ensure HVE Core exists at ${localWorkspaceFolder}/../hve-core
3. Remove the mount temporarily to start the container
4. Clone HVE Core, then add mount back and rebuild

Agents Not Appearing

Check mount is working

# Inside container
ls /workspaces/hve-core/.github/agents

Check settings paths match

Settings must use absolute container paths (/workspaces/hve-core/...), not relative paths.

Doesn't Work in Codespaces

This is expected. Codespaces doesn't support ${localWorkspaceFolder} or host bind mounts.

Solution: Use postCreateCommand for Codespaces, or Multi-Root Workspace for dual-environment support.

Limitations

Aspect	Status
Devcontainers	✅ Full support
Codespaces	❌ Not supported (no host access)
Team sharing	⚠️ Each developer clones on their host
Portable paths	⚠️ Absolute container paths
Version pinning	⚠️ Manual (use git checkout on host)
Shared installation	✅ One clone serves all projects
Setup complexity	⚠️ High (multi-phase, requires rebuild)
Update process	✅ Just git pull on host

Next Steps

• Your First Workflow - Try HVE Core with a real task
• Multi-Root Workspace - Simpler portable solution
• postCreateCommand - If you also need Codespaces support

---

🤖 Crafted with precision by ✨Copilot following brilliant human instruction, then carefully refined by our team of discerning human reviewers.