hve-core/docs/getting-started/methods/mounted.md at main · microsoft/hve-core

title

Mounted Directory Installation

description

Advanced devcontainer setup mounting HVE Core from host filesystem

sidebar_position

author

Microsoft

ms.date

2026-03-10

ms.topic

how-to

keywords

mounted directory

installation

github copilot

devcontainer

advanced

estimated_reading_time

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.

Press Ctrl+Shift+P (or Cmd+Shift+P on macOS)
Type "Dev Containers: Rebuild Container"
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,
    "/workspaces/hve-core/.github/skills/coding-standards": 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,
          "/workspaces/hve-core/.github/skills/coding-standards": true
        }
      }
    }
  }
}

Phase 5: Validate Installation

Open GitHub Copilot Chat (Ctrl+Alt+I)
Click the agent picker dropdown
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,
          "/workspaces/hve-core/.github/skills/coding-standards": 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

Exit the container
Clone HVE Core on your host machine (see Phase 1)
Verify the path matches the mount source
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

Check devcontainer.json mount path
Ensure HVE Core exists at ${localWorkspaceFolder}/../hve-core
Remove the mount temporarily to start the container
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.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

When to Use This Method

⚠️ Important Limitations

How It Works

Installation Workflow

Quick Start

Manual Setup

Phase 1: Clone HVE Core on Host

Phase 2: Add Mount to devcontainer.json

Alternative object format

Phase 3: Rebuild Container

What happens during rebuild

Phase 4: Configure VS Code Settings

Phase 5: Validate Installation

Verify mount from container terminal

Complete Devcontainer Example

Updating HVE Core

Troubleshooting

Mount Point Empty After Rebuild

Fix

Check from host terminal

Container Fails to Start

Fix

Agents Not Appearing

Check mount is working

Check settings paths match

Doesn't Work in Codespaces

Limitations

Next Steps

FilesExpand file tree

mounted.md

Latest commit

History

mounted.md

File metadata and controls

When to Use This Method

⚠️ Important Limitations

How It Works

Installation Workflow

Quick Start

Manual Setup

Phase 1: Clone HVE Core on Host

Phase 2: Add Mount to devcontainer.json

Alternative object format

Phase 3: Rebuild Container

What happens during rebuild

Phase 4: Configure VS Code Settings

Phase 5: Validate Installation

Verify mount from container terminal

Complete Devcontainer Example

Updating HVE Core

Troubleshooting

Mount Point Empty After Rebuild

Fix

Check from host terminal

Container Fails to Start

Fix

Agents Not Appearing

Check mount is working

Check settings paths match

Doesn't Work in Codespaces

Limitations

Next Steps