GitVita
New repositoryImport repositoryNew issue
Your repositories Your dashboard Sign in

microsoft/hve-core

Public

mirrored fromhttps://github.com/microsoft/hve-coreAvailable

Watch0Fork0Star0
CodeCommitsIssuesPull requestsActionsInsightsSecurity
3a3a0fdf923d96a9e8a9ac734c73f24433b525e8

Branches

Tags

  • No tags available.
0Branches0Tags
Go to file
Add file
Code

Clone

HTTPS

Download ZIP

hve-core/docs/getting-started/methods

docs/getting-started/methods/mounted.md

379lines · modecode

RawDownload
Latest commit unavailable.
1---
2title: Mounted Directory Installation
3description: Advanced devcontainer setup mounting HVE-Core from host filesystem
4sidebar_position: 5
5author: Microsoft
6ms.date: 2026-03-10
7ms.topic: how-to
8keywords:
9 - mounted directory
10 - installation
11 - github copilot
12 - devcontainer
13 - advanced
14estimated_reading_time: 8
15---
16
17Mounted 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.
18
19## When to Use This Method
20
21✅ **Use this when:**
22
23* You have multiple devcontainer projects needing HVE-Core
24* You want a single shared installation (one update applies everywhere)
25* You're comfortable with devcontainer configuration
26* You're using local devcontainers only (not Codespaces)
27
28❌ **Consider alternatives when:**
29
30* You use Codespaces → [GitHub Codespaces](codespaces.md) (mounts don't work)
31* You want simpler setup → [Git-Ignored Folder](git-ignored.md)
32* Your team needs version control → [Submodule](submodule.md)
33* You need paths that work everywhere → [Multi-Root Workspace](multi-root.md)
34
35## ⚠️ Important Limitations
36
37**This method does NOT work in GitHub Codespaces.** Codespaces doesn't support `${localWorkspaceFolder}` or bind mounts to host filesystem.
38
39**Requires container rebuild.** After adding the mount, you must rebuild the devcontainer before HVE-Core becomes accessible.
40
41## How It Works
42
43HVE-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`.
44
45```text
46Host File System:
47projects/
48├── my-project/ # Your project (workspace)
49│ └── .devcontainer/
50│ └── devcontainer.json # Contains mount configuration
51│
52└── hve-core/ # Peer directory on HOST
53 └── .github/
54 ├── agents/
55 ├── prompts/
56 └── instructions/
57
58Inside Container (after rebuild):
59/workspaces/
60├── my-project/ # Mounted workspace
61└── hve-core/ # Mounted peer directory
62```
63
64## Installation Workflow
65
66This method requires a multi-phase workflow:
67
68```text
69┌─────────────────────────────────────────────────────────────┐
70│ Phase 1: Clone HVE-Core on HOST │
71│ ↓ │
72│ Phase 2: Add mount to devcontainer.json │
73│ ↓ │
74│ Phase 3: Rebuild container (1-3 minutes) │
75│ ↓ │
76│ Phase 4: Configure VS Code settings │
77│ ↓ │
78│ Phase 5: Validate installation │
79└─────────────────────────────────────────────────────────────┘
80```
81
82## Quick Start
83
84Install the [VS Code extension](https://marketplace.visualstudio.com/items?itemName=ise-hve-essentials.hve-core) for the fastest setup. For guided setup with installation method selection and MCP configuration, install the [HVE Core Installer](https://marketplace.visualstudio.com/items?itemName=ise-hve-essentials.hve-installer) extension and ask any agent "help me customize hve-core installation". Use the manual steps below for direct configuration.
85
86## Manual Setup
87
88### Phase 1: Clone HVE-Core on Host
89
90**Important:** Clone on your **host machine**, not inside the container.
91
92Open a terminal on your host (not in VS Code's container terminal):
93
94```bash
95# Navigate to parent of your project
96cd /path/to/projects
97
98# Clone HVE-Core as a sibling
99git clone https://github.com/microsoft/hve-core.git
100```
101
102Verify structure:
103
104```text
105projects/
106├── my-project/
107└── hve-core/ # ← Must exist on HOST before rebuild
108```
109
110### Phase 2: Add Mount to devcontainer.json
111
112Update `.devcontainer/devcontainer.json`:
113
114```jsonc
115{
116 // ... existing configuration ...
117
118 "mounts": [
119 "source=${localWorkspaceFolder}/../hve-core,target=/workspaces/hve-core,type=bind,readonly=true,consistency=cached"
120 ]
121}
122```
123
124#### Alternative object format
125
126```jsonc
127{
128 "mounts": [
129 {
130 "type": "bind",
131 "source": "${localWorkspaceFolder}/../hve-core",
132 "target": "/workspaces/hve-core"
133 }
134 ]
135}
136```
137
138### Phase 3: Rebuild Container
139
140⚠️ **Container rebuild is required** to apply the mount.
141
1421. Press `Ctrl+Shift+P` (or `Cmd+Shift+P` on macOS)
1432. Type "Dev Containers: Rebuild Container"
1443. Press Enter and wait for rebuild (1-3 minutes)
145
146#### What happens during rebuild
147
148* Current container stops
149* New container builds with mount configuration
150* Extensions reinstall
151* Lifecycle scripts re-run
152
153### Phase 4: Configure VS Code Settings
154
155After rebuild, update `.vscode/settings.json`:
156
157```json
158{
159 "chat.agentFilesLocations": {
160 "/workspaces/hve-core/.github/agents/ado": true,
161 "/workspaces/hve-core/.github/agents/data-science": true,
162 "/workspaces/hve-core/.github/agents/design-thinking": true,
163 "/workspaces/hve-core/.github/agents/github": true,
164 "/workspaces/hve-core/.github/agents/project-planning": true,
165 "/workspaces/hve-core/.github/agents/hve-core": true,
166 "/workspaces/hve-core/.github/agents/hve-core/subagents": true,
167 "/workspaces/hve-core/.github/agents/security": true
168 },
169 "chat.promptFilesLocations": {
170 "/workspaces/hve-core/.github/prompts/ado": true,
171 "/workspaces/hve-core/.github/prompts/design-thinking": true,
172 "/workspaces/hve-core/.github/prompts/github": true,
173 "/workspaces/hve-core/.github/prompts/hve-core": true,
174 "/workspaces/hve-core/.github/prompts/security": true
175 },
176 "chat.instructionsFilesLocations": {
177 "/workspaces/hve-core/.github/instructions/ado": true,
178 "/workspaces/hve-core/.github/instructions/coding-standards": true,
179 "/workspaces/hve-core/.github/instructions/design-thinking": true,
180 "/workspaces/hve-core/.github/instructions/github": true,
181 "/workspaces/hve-core/.github/instructions/hve-core": true,
182 "/workspaces/hve-core/.github/instructions/shared": true
183 },
184 "chat.agentSkillsLocations": {
185 "/workspaces/hve-core/.github/skills": true,
186 "/workspaces/hve-core/.github/skills/shared": true
187 }
188}
189```
190
191**Or add to devcontainer.json** (recommended for team sharing):
192
193```jsonc
194{
195 "customizations": {
196 "vscode": {
197 "settings": {
198 "chat.agentFilesLocations": {
199 "/workspaces/hve-core/.github/agents/ado": true,
200 "/workspaces/hve-core/.github/agents/data-science": true,
201 "/workspaces/hve-core/.github/agents/design-thinking": true,
202 "/workspaces/hve-core/.github/agents/github": true,
203 "/workspaces/hve-core/.github/agents/project-planning": true,
204 "/workspaces/hve-core/.github/agents/hve-core": true,
205 "/workspaces/hve-core/.github/agents/hve-core/subagents": true,
206 "/workspaces/hve-core/.github/agents/security": true
207 },
208 "chat.promptFilesLocations": {
209 "/workspaces/hve-core/.github/prompts/ado": true,
210 "/workspaces/hve-core/.github/prompts/design-thinking": true,
211 "/workspaces/hve-core/.github/prompts/github": true,
212 "/workspaces/hve-core/.github/prompts/hve-core": true,
213 "/workspaces/hve-core/.github/prompts/security": true
214 },
215 "chat.instructionsFilesLocations": {
216 "/workspaces/hve-core/.github/instructions/ado": true,
217 "/workspaces/hve-core/.github/instructions/coding-standards": true,
218 "/workspaces/hve-core/.github/instructions/design-thinking": true,
219 "/workspaces/hve-core/.github/instructions/github": true,
220 "/workspaces/hve-core/.github/instructions/hve-core": true,
221 "/workspaces/hve-core/.github/instructions/shared": true
222 },
223 "chat.agentSkillsLocations": {
224 "/workspaces/hve-core/.github/skills": true,
225 "/workspaces/hve-core/.github/skills/shared": true
226 }
227 }
228 }
229 }
230}
231```
232
233### Phase 5: Validate Installation
234
2351. Open GitHub Copilot Chat (`Ctrl+Alt+I`)
2362. Click the agent picker dropdown
2373. Verify HVE-Core agents appear (task-planner, task-researcher, prompt-builder)
238
239#### Verify mount from container terminal
240
241```bash
242ls /workspaces/hve-core/.github/agents
243```
244
245## Complete Devcontainer Example
246
247```jsonc
248{
249 "name": "My Project with Mounted HVE-Core",
250 "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
251
252 "mounts": [
253 "source=${localWorkspaceFolder}/../hve-core,target=/workspaces/hve-core,type=bind,readonly=true,consistency=cached"
254 ],
255
256 "customizations": {
257 "vscode": {
258 "settings": {
259 "chat.agentFilesLocations": {
260 "/workspaces/hve-core/.github/agents/ado": true,
261 "/workspaces/hve-core/.github/agents/data-science": true,
262 "/workspaces/hve-core/.github/agents/design-thinking": true,
263 "/workspaces/hve-core/.github/agents/github": true,
264 "/workspaces/hve-core/.github/agents/project-planning": true,
265 "/workspaces/hve-core/.github/agents/hve-core": true,
266 "/workspaces/hve-core/.github/agents/hve-core/subagents": true,
267 "/workspaces/hve-core/.github/agents/security": true
268 },
269 "chat.promptFilesLocations": {
270 "/workspaces/hve-core/.github/prompts/ado": true,
271 "/workspaces/hve-core/.github/prompts/design-thinking": true,
272 "/workspaces/hve-core/.github/prompts/github": true,
273 "/workspaces/hve-core/.github/prompts/hve-core": true,
274 "/workspaces/hve-core/.github/prompts/security": true
275 },
276 "chat.instructionsFilesLocations": {
277 "/workspaces/hve-core/.github/instructions/ado": true,
278 "/workspaces/hve-core/.github/instructions/coding-standards": true,
279 "/workspaces/hve-core/.github/instructions/design-thinking": true,
280 "/workspaces/hve-core/.github/instructions/github": true,
281 "/workspaces/hve-core/.github/instructions/hve-core": true,
282 "/workspaces/hve-core/.github/instructions/shared": true
283 },
284 "chat.agentSkillsLocations": {
285 "/workspaces/hve-core/.github/skills": true,
286 "/workspaces/hve-core/.github/skills/shared": true
287 }
288 }
289 }
290 }
291}
292```
293
294## Updating HVE-Core
295
296Update on your host machine:
297
298```bash
299cd /path/to/projects/hve-core
300git pull
301```
302
303Changes are immediately available in all containers using the mount. No rebuild required for content updates.
304
305## Troubleshooting
306
307### Mount Point Empty After Rebuild
308
309**Cause:** HVE-Core wasn't cloned on the host, or was cloned in the wrong location.
310
311#### Fix
312
3131. Exit the container
3142. Clone HVE-Core on your host machine (see Phase 1)
3153. Verify the path matches the mount source
3164. Rebuild the container
317
318#### Check from host terminal
319
320```bash
321# On host, not in container
322ls /path/to/projects/hve-core/.github
323```
324
325### Container Fails to Start
326
327**Cause:** Mount source path doesn't exist.
328
329#### Fix
330
3311. Check `devcontainer.json` mount path
3322. Ensure HVE-Core exists at `${localWorkspaceFolder}/../hve-core`
3333. Remove the mount temporarily to start the container
3344. Clone HVE-Core, then add mount back and rebuild
335
336### Agents Not Appearing
337
338#### Check mount is working
339
340```bash
341# Inside container
342ls /workspaces/hve-core/.github/agents
343```
344
345#### Check settings paths match
346
347Settings must use absolute container paths (`/workspaces/hve-core/...`), not relative paths.
348
349### Doesn't Work in Codespaces
350
351This is expected. Codespaces doesn't support `${localWorkspaceFolder}` or host bind mounts.
352
353**Solution:** Use [postCreateCommand](codespaces.md) for Codespaces, or [Multi-Root Workspace](multi-root.md) for dual-environment support.
354
355## Limitations
356
357| Aspect | Status |
358|---------------------|------------------------------------------|
359| Devcontainers | ✅ Full support |
360| Codespaces | ❌ Not supported (no host access) |
361| Team sharing | ⚠️ Each developer clones on their host |
362| Portable paths | ⚠️ Absolute container paths |
363| Version pinning | ⚠️ Manual (use git checkout on host) |
364| Shared installation | ✅ One clone serves all projects |
365| Setup complexity | ⚠️ High (multi-phase, requires rebuild) |
366| Update process | ✅ Just git pull on host |
367
368## Next Steps
369
370* [Your First Workflow](../first-workflow.md) - Try HVE-Core with a real task
371* [Multi-Root Workspace](multi-root.md) - Simpler portable solution
372* [postCreateCommand](codespaces.md) - If you also need Codespaces support
373
374---
375
376<!-- markdownlint-disable MD036 -->
377*🤖 Crafted with precision by ✨Copilot following brilliant human instruction,
378then carefully refined by our team of discerning human reviewers.*
379<!-- markdownlint-enable MD036 -->