microsoft/hve-core

Public

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

Watch0 Fork0 Star0

Code Commits Issues Pull requests Actions Insights Security

hve-core-v2.1.0

Find a branch or tag

Branches

hve-core-v2.1.0

Clone

HTTPS

Download ZIP

hve-core/docs/getting-started/methods

docs/getting-started/methods/mounted.md

305lines · modecode

Raw Download

Latest commit unavailable.

unknown

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

microsoft/hve-core

Branches

Tags

Clone