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
hve-core-v3.3.10

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 -->
380