GitVita
New repositoryImport repositoryNew issue
Your repositories Your dashboard Sign in

microsoft/hve-core

Public

mirrored from https://github.com/microsoft/hve-coreAvailable

Watch0Fork0Star0
CodeCommitsIssuesPull requestsActionsInsightsSecurity
f40cb207c87bc3b1680e68af9fccfe4f02577f22

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

387lines · 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: 2025-12-03
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
84Use the `hve-core-installer` agent:
85
861. Open GitHub Copilot Chat (`Ctrl+Alt+I`)
872. Select `hve-core-installer` from the agent picker
883. Say: "Install HVE-Core using mounted directory"
894. Follow the multi-phase guided setup
90
91## Manual Setup
92
93### Phase 1: Clone HVE-Core on Host
94
95**Important:** Clone on your **host machine**, not inside the container.
96
97Open a terminal on your host (not in VS Code's container terminal):
98
99```bash
100# Navigate to parent of your project
101cd /path/to/projects
102
103# Clone HVE-Core as a sibling
104git clone https://github.com/microsoft/hve-core.git
105```
106
107Verify structure:
108
109```text
110projects/
111├── my-project/
112└── hve-core/ # ← Must exist on HOST before rebuild
113```
114
115### Phase 2: Add Mount to devcontainer.json
116
117Update `.devcontainer/devcontainer.json`:
118
119```jsonc
120{
121 // ... existing configuration ...
122
123 "mounts": [
124 "source=${localWorkspaceFolder}/../hve-core,target=/workspaces/hve-core,type=bind,readonly=true,consistency=cached"
125 ]
126}
127```
128
129#### Alternative object format
130
131```jsonc
132{
133 "mounts": [
134 {
135 "type": "bind",
136 "source": "${localWorkspaceFolder}/../hve-core",
137 "target": "/workspaces/hve-core"
138 }
139 ]
140}
141```
142
143### Phase 3: Rebuild Container
144
145⚠️ **Container rebuild is required** to apply the mount.
146
1471. Press `Ctrl+Shift+P` (or `Cmd+Shift+P` on macOS)
1482. Type "Dev Containers: Rebuild Container"
1493. Press Enter and wait for rebuild (1-3 minutes)
150
151#### What happens during rebuild
152
153* Current container stops
154* New container builds with mount configuration
155* Extensions reinstall
156* Lifecycle scripts re-run
157
158### Phase 4: Configure VS Code Settings
159
160After rebuild, update `.vscode/settings.json`:
161
162```json
163{
164 "chat.agentFilesLocations": {
165 "/workspaces/hve-core/.github/agents/ado": true,
166 "/workspaces/hve-core/.github/agents/data-science": true,
167 "/workspaces/hve-core/.github/agents/design-thinking": true,
168 "/workspaces/hve-core/.github/agents/github": true,
169 "/workspaces/hve-core/.github/agents/installer": true,
170 "/workspaces/hve-core/.github/agents/project-planning": true,
171 "/workspaces/hve-core/.github/agents/hve-core": true,
172 "/workspaces/hve-core/.github/agents/hve-core/subagents": true,
173 "/workspaces/hve-core/.github/agents/security-planning": true
174 },
175 "chat.promptFilesLocations": {
176 "/workspaces/hve-core/.github/prompts/ado": true,
177 "/workspaces/hve-core/.github/prompts/design-thinking": true,
178 "/workspaces/hve-core/.github/prompts/github": true,
179 "/workspaces/hve-core/.github/prompts/hve-core": true,
180 "/workspaces/hve-core/.github/prompts/security-planning": true
181 },
182 "chat.instructionsFilesLocations": {
183 "/workspaces/hve-core/.github/instructions/ado": true,
184 "/workspaces/hve-core/.github/instructions/coding-standards": true,
185 "/workspaces/hve-core/.github/instructions/design-thinking": true,
186 "/workspaces/hve-core/.github/instructions/github": true,
187 "/workspaces/hve-core/.github/instructions/hve-core": true,
188 "/workspaces/hve-core/.github/instructions/shared": true
189 },
190 "chat.agentSkillsLocations": {
191 "/workspaces/hve-core/.github/skills": true,
192 "/workspaces/hve-core/.github/skills/shared": true
193 }
194}
195```
196
197**Or add to devcontainer.json** (recommended for team sharing):
198
199```jsonc
200{
201 "customizations": {
202 "vscode": {
203 "settings": {
204 "chat.agentFilesLocations": {
205 "/workspaces/hve-core/.github/agents/ado": true,
206 "/workspaces/hve-core/.github/agents/data-science": true,
207 "/workspaces/hve-core/.github/agents/design-thinking": true,
208 "/workspaces/hve-core/.github/agents/github": true,
209 "/workspaces/hve-core/.github/agents/installer": true,
210 "/workspaces/hve-core/.github/agents/project-planning": true,
211 "/workspaces/hve-core/.github/agents/hve-core": true,
212 "/workspaces/hve-core/.github/agents/hve-core/subagents": true,
213 "/workspaces/hve-core/.github/agents/security-planning": true
214 },
215 "chat.promptFilesLocations": {
216 "/workspaces/hve-core/.github/prompts/ado": true,
217 "/workspaces/hve-core/.github/prompts/design-thinking": true,
218 "/workspaces/hve-core/.github/prompts/github": true,
219 "/workspaces/hve-core/.github/prompts/hve-core": true,
220 "/workspaces/hve-core/.github/prompts/security-planning": true
221 },
222 "chat.instructionsFilesLocations": {
223 "/workspaces/hve-core/.github/instructions/ado": true,
224 "/workspaces/hve-core/.github/instructions/coding-standards": true,
225 "/workspaces/hve-core/.github/instructions/design-thinking": true,
226 "/workspaces/hve-core/.github/instructions/github": true,
227 "/workspaces/hve-core/.github/instructions/hve-core": true,
228 "/workspaces/hve-core/.github/instructions/shared": true
229 },
230 "chat.agentSkillsLocations": {
231 "/workspaces/hve-core/.github/skills": true,
232 "/workspaces/hve-core/.github/skills/shared": true
233 }
234 }
235 }
236 }
237}
238```
239
240### Phase 5: Validate Installation
241
2421. Open GitHub Copilot Chat (`Ctrl+Alt+I`)
2432. Click the agent picker dropdown
2443. Verify HVE-Core agents appear (task-planner, task-researcher, prompt-builder)
245
246#### Verify mount from container terminal
247
248```bash
249ls /workspaces/hve-core/.github/agents
250```
251
252## Complete Devcontainer Example
253
254```jsonc
255{
256 "name": "My Project with Mounted HVE-Core",
257 "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
258
259 "mounts": [
260 "source=${localWorkspaceFolder}/../hve-core,target=/workspaces/hve-core,type=bind,readonly=true,consistency=cached"
261 ],
262
263 "customizations": {
264 "vscode": {
265 "settings": {
266 "chat.agentFilesLocations": {
267 "/workspaces/hve-core/.github/agents/ado": true,
268 "/workspaces/hve-core/.github/agents/data-science": true,
269 "/workspaces/hve-core/.github/agents/design-thinking": true,
270 "/workspaces/hve-core/.github/agents/github": true,
271 "/workspaces/hve-core/.github/agents/installer": true,
272 "/workspaces/hve-core/.github/agents/project-planning": true,
273 "/workspaces/hve-core/.github/agents/hve-core": true,
274 "/workspaces/hve-core/.github/agents/hve-core/subagents": true,
275 "/workspaces/hve-core/.github/agents/security-planning": true
276 },
277 "chat.promptFilesLocations": {
278 "/workspaces/hve-core/.github/prompts/ado": true,
279 "/workspaces/hve-core/.github/prompts/design-thinking": true,
280 "/workspaces/hve-core/.github/prompts/github": true,
281 "/workspaces/hve-core/.github/prompts/hve-core": true,
282 "/workspaces/hve-core/.github/prompts/security-planning": true
283 },
284 "chat.instructionsFilesLocations": {
285 "/workspaces/hve-core/.github/instructions/ado": true,
286 "/workspaces/hve-core/.github/instructions/coding-standards": true,
287 "/workspaces/hve-core/.github/instructions/design-thinking": true,
288 "/workspaces/hve-core/.github/instructions/github": true,
289 "/workspaces/hve-core/.github/instructions/hve-core": true,
290 "/workspaces/hve-core/.github/instructions/shared": true
291 },
292 "chat.agentSkillsLocations": {
293 "/workspaces/hve-core/.github/skills": true,
294 "/workspaces/hve-core/.github/skills/shared": true
295 }
296 }
297 }
298 }
299}
300```
301
302## Updating HVE-Core
303
304Update on your host machine:
305
306```bash
307cd /path/to/projects/hve-core
308git pull
309```
310
311Changes are immediately available in all containers using the mount. No rebuild required for content updates.
312
313## Troubleshooting
314
315### Mount Point Empty After Rebuild
316
317**Cause:** HVE-Core wasn't cloned on the host, or was cloned in the wrong location.
318
319#### Fix
320
3211. Exit the container
3222. Clone HVE-Core on your host machine (see Phase 1)
3233. Verify the path matches the mount source
3244. Rebuild the container
325
326#### Check from host terminal
327
328```bash
329# On host, not in container
330ls /path/to/projects/hve-core/.github
331```
332
333### Container Fails to Start
334
335**Cause:** Mount source path doesn't exist.
336
337#### Fix
338
3391. Check `devcontainer.json` mount path
3402. Ensure HVE-Core exists at `${localWorkspaceFolder}/../hve-core`
3413. Remove the mount temporarily to start the container
3424. Clone HVE-Core, then add mount back and rebuild
343
344### Agents Not Appearing
345
346#### Check mount is working
347
348```bash
349# Inside container
350ls /workspaces/hve-core/.github/agents
351```
352
353#### Check settings paths match
354
355Settings must use absolute container paths (`/workspaces/hve-core/...`), not relative paths.
356
357### Doesn't Work in Codespaces
358
359This is expected. Codespaces doesn't support `${localWorkspaceFolder}` or host bind mounts.
360
361**Solution:** Use [postCreateCommand](codespaces.md) for Codespaces, or [Multi-Root Workspace](multi-root.md) for dual-environment support.
362
363## Limitations
364
365| Aspect | Status |
366|---------------------|------------------------------------------|
367| Devcontainers | ✅ Full support |
368| Codespaces | ❌ Not supported (no host access) |
369| Team sharing | ⚠️ Each developer clones on their host |
370| Portable paths | ⚠️ Absolute container paths |
371| Version pinning | ⚠️ Manual (use git checkout on host) |
372| Shared installation | ✅ One clone serves all projects |
373| Setup complexity | ⚠️ High (multi-phase, requires rebuild) |
374| Update process | ✅ Just git pull on host |
375
376## Next Steps
377
378* [Your First Workflow](../first-workflow.md) - Try HVE-Core with a real task
379* [Multi-Root Workspace](multi-root.md) - Simpler portable solution
380* [postCreateCommand](codespaces.md) - If you also need Codespaces support
381
382---
383
384<!-- markdownlint-disable MD036 -->
385*🤖 Crafted with precision by ✨Copilot following brilliant human instruction,
386then carefully refined by our team of discerning human reviewers.*
387<!-- markdownlint-enable MD036 -->