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
83a260607c12fda28c813d44de416bad498156ff

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

382lines · 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-06-11
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/github": true,
180 "/workspaces/hve-core/.github/instructions/hve-core": true,
181 "/workspaces/hve-core/.github/instructions/shared": true
182 },
183 "chat.agentSkillsLocations": {
184 "/workspaces/hve-core/.github/skills": true,
185 "/workspaces/hve-core/.github/skills/shared": true,
186 "/workspaces/hve-core/.github/skills/coding-standards": true,
187 "/workspaces/hve-core/.github/skills/design-thinking": true
188 }
189}
190```
191
192**Or add to devcontainer.json** (recommended for team sharing):
193
194```jsonc
195{
196 "customizations": {
197 "vscode": {
198 "settings": {
199 "chat.agentFilesLocations": {
200 "/workspaces/hve-core/.github/agents/ado": true,
201 "/workspaces/hve-core/.github/agents/data-science": true,
202 "/workspaces/hve-core/.github/agents/design-thinking": true,
203 "/workspaces/hve-core/.github/agents/github": true,
204 "/workspaces/hve-core/.github/agents/project-planning": true,
205 "/workspaces/hve-core/.github/agents/hve-core": true,
206 "/workspaces/hve-core/.github/agents/hve-core/subagents": true,
207 "/workspaces/hve-core/.github/agents/security": true
208 },
209 "chat.promptFilesLocations": {
210 "/workspaces/hve-core/.github/prompts/ado": true,
211 "/workspaces/hve-core/.github/prompts/design-thinking": true,
212 "/workspaces/hve-core/.github/prompts/github": true,
213 "/workspaces/hve-core/.github/prompts/hve-core": true,
214 "/workspaces/hve-core/.github/prompts/security": true
215 },
216 "chat.instructionsFilesLocations": {
217 "/workspaces/hve-core/.github/instructions/ado": true,
218 "/workspaces/hve-core/.github/instructions/coding-standards": 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 "/workspaces/hve-core/.github/skills/coding-standards": true,
227 "/workspaces/hve-core/.github/skills/design-thinking": true
228 }
229 }
230 }
231 }
232}
233```
234
235### Phase 5: Validate Installation
236
2371. Open GitHub Copilot Chat (`Ctrl+Alt+I`)
2382. Click the agent picker dropdown
2393. Verify HVE Core agents appear (task-planner, task-researcher, prompt-builder)
240
241#### Verify mount from container terminal
242
243```bash
244ls /workspaces/hve-core/.github/agents
245```
246
247## Complete Devcontainer Example
248
249```jsonc
250{
251 "name": "My Project with Mounted HVE Core",
252 "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
253
254 "mounts": [
255 "source=${localWorkspaceFolder}/../hve-core,target=/workspaces/hve-core,type=bind,readonly=true,consistency=cached"
256 ],
257
258 "customizations": {
259 "vscode": {
260 "settings": {
261 "chat.agentFilesLocations": {
262 "/workspaces/hve-core/.github/agents/ado": true,
263 "/workspaces/hve-core/.github/agents/data-science": true,
264 "/workspaces/hve-core/.github/agents/design-thinking": true,
265 "/workspaces/hve-core/.github/agents/github": true,
266 "/workspaces/hve-core/.github/agents/project-planning": true,
267 "/workspaces/hve-core/.github/agents/hve-core": true,
268 "/workspaces/hve-core/.github/agents/hve-core/subagents": true,
269 "/workspaces/hve-core/.github/agents/security": true
270 },
271 "chat.promptFilesLocations": {
272 "/workspaces/hve-core/.github/prompts/ado": true,
273 "/workspaces/hve-core/.github/prompts/design-thinking": true,
274 "/workspaces/hve-core/.github/prompts/github": true,
275 "/workspaces/hve-core/.github/prompts/hve-core": true,
276 "/workspaces/hve-core/.github/prompts/security": true
277 },
278 "chat.instructionsFilesLocations": {
279 "/workspaces/hve-core/.github/instructions/ado": true,
280 "/workspaces/hve-core/.github/instructions/coding-standards": true,
281 "/workspaces/hve-core/.github/instructions/github": true,
282 "/workspaces/hve-core/.github/instructions/hve-core": true,
283 "/workspaces/hve-core/.github/instructions/shared": true
284 },
285 "chat.agentSkillsLocations": {
286 "/workspaces/hve-core/.github/skills": true,
287 "/workspaces/hve-core/.github/skills/shared": true,
288 "/workspaces/hve-core/.github/skills/coding-standards": true,
289 "/workspaces/hve-core/.github/skills/design-thinking": true
290 }
291 }
292 }
293 }
294}
295```
296
297## Updating HVE Core
298
299Update on your host machine:
300
301```bash
302cd /path/to/projects/hve-core
303git pull
304```
305
306Changes are immediately available in all containers using the mount. No rebuild required for content updates.
307
308## Troubleshooting
309
310### Mount Point Empty After Rebuild
311
312**Cause:** HVE Core wasn't cloned on the host, or was cloned in the wrong location.
313
314#### Fix
315
3161. Exit the container
3172. Clone HVE Core on your host machine (see Phase 1)
3183. Verify the path matches the mount source
3194. Rebuild the container
320
321#### Check from host terminal
322
323```bash
324# On host, not in container
325ls /path/to/projects/hve-core/.github
326```
327
328### Container Fails to Start
329
330**Cause:** Mount source path doesn't exist.
331
332#### Fix
333
3341. Check `devcontainer.json` mount path
3352. Ensure HVE Core exists at `${localWorkspaceFolder}/../hve-core`
3363. Remove the mount temporarily to start the container
3374. Clone HVE Core, then add mount back and rebuild
338
339### Agents Not Appearing
340
341#### Check mount is working
342
343```bash
344# Inside container
345ls /workspaces/hve-core/.github/agents
346```
347
348#### Check settings paths match
349
350Settings must use absolute container paths (`/workspaces/hve-core/...`), not relative paths.
351
352### Doesn't Work in Codespaces
353
354This is expected. Codespaces doesn't support `${localWorkspaceFolder}` or host bind mounts.
355
356**Solution:** Use [postCreateCommand](codespaces.md) for Codespaces, or [Multi-Root Workspace](multi-root.md) for dual-environment support.
357
358## Limitations
359
360| Aspect | Status |
361|---------------------|------------------------------------------|
362| Devcontainers | ✅ Full support |
363| Codespaces | ❌ Not supported (no host access) |
364| Team sharing | ⚠️ Each developer clones on their host |
365| Portable paths | ⚠️ Absolute container paths |
366| Version pinning | ⚠️ Manual (use git checkout on host) |
367| Shared installation | ✅ One clone serves all projects |
368| Setup complexity | ⚠️ High (multi-phase, requires rebuild) |
369| Update process | ✅ Just git pull on host |
370
371## Next Steps
372
373* [Your First Workflow](../first-workflow.md) - Try HVE Core with a real task
374* [Multi-Root Workspace](multi-root.md) - Simpler portable solution
375* [postCreateCommand](codespaces.md) - If you also need Codespaces support
376
377---
378
379<!-- markdownlint-disable MD036 -->
380*🤖 Crafted with precision by ✨Copilot following brilliant human instruction,
381then carefully refined by our team of discerning human reviewers.*
382<!-- markdownlint-enable MD036 -->
383