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
c330c7aabebb16d36787e09c239c99de34d6cfcb

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/codespaces.md

439lines · modecode

RawDownload
Latest commit unavailable.
1---
2title: GitHub Codespaces Installation
3description: Install HVE Core in GitHub Codespaces using postCreateCommand
4sidebar_position: 8
5author: Microsoft
6ms.date: 2026-03-10
7ms.topic: how-to
8keywords:
9 - codespaces
10 - installation
11 - github copilot
12 - postCreateCommand
13 - cloud development
14estimated_reading_time: 7
15---
16
17GitHub Codespaces requires a specific installation approach because traditional methods (peer directories, bind mounts) don't work in cloud environments. This method uses `postCreateCommand` to clone HVE Core into the persistent `/workspaces` directory.
18
19## When to Use This Method
20
21✅ **Use this when:**
22
23* Your project runs exclusively in Codespaces
24* You want automatic HVE Core setup for all users
25* You need zero-config onboarding for contributors
26
27❌ **Consider alternatives when:**
28
29* You also need local devcontainer support → [Multi-Root Workspace](multi-root.md)
30* Your team needs version control → [Submodule](submodule.md)
31* You're using local VS Code only → [Peer Clone](peer-clone.md)
32
33## Why Other Methods Don't Work in Codespaces
34
35| Feature | Local Devcontainer | GitHub Codespaces |
36|----------------------------|--------------------|------------------------------|
37| `${localWorkspaceFolder}` | ✅ Resolves to host | ❌ Not available |
38| Bind mounts to host | ✅ Full support | ❌ No host access |
39| Persistent storage | Host filesystem | `/workspaces` only |
40| User settings modification | ✅ Via file system | ❌ Only via Settings Sync[^1] |
41
42[^1]: User-level settings require Settings Sync. Workspace/container-level settings can still be configured via `devcontainer.json` using `customizations.vscode.settings`.
43
44## How It Works
45
46Codespaces has a specific storage model:
47
48```text
49/
50├── workspaces/ # ✅ PERSISTENT - survives stops/restarts
51│ ├── your-repo/ # Your cloned repository
52│ └── hve-core/ # 👈 HVE Core goes here
53├── home/codespace/ # ⚠️ Semi-persistent (survives stops, not rebuilds)
54└── <system-dirs>/ # ❌ Not persistent
55```
56
57The `postCreateCommand` clones HVE Core into `/workspaces/hve-core` where it persists across Codespace sessions.
58
59## Quick Start
60
61Install 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.
62
63## Manual Setup
64
65### Step 1: Update devcontainer.json
66
67Add the clone command and VS Code settings:
68
69```jsonc
70{
71 "name": "My Project with HVE Core",
72 "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
73
74 "postCreateCommand": "[ -d /workspaces/hve-core ] || git clone --depth 1 https://github.com/microsoft/hve-core.git /workspaces/hve-core",
75
76 "customizations": {
77 "vscode": {
78 "settings": {
79 "chat.agentFilesLocations": {
80 "/workspaces/hve-core/.github/agents/ado": true,
81 "/workspaces/hve-core/.github/agents/data-science": true,
82 "/workspaces/hve-core/.github/agents/design-thinking": true,
83 "/workspaces/hve-core/.github/agents/github": true,
84 "/workspaces/hve-core/.github/agents/project-planning": true,
85 "/workspaces/hve-core/.github/agents/hve-core": true,
86 "/workspaces/hve-core/.github/agents/hve-core/subagents": true,
87 "/workspaces/hve-core/.github/agents/security": true
88 },
89 "chat.promptFilesLocations": {
90 "/workspaces/hve-core/.github/prompts/ado": true,
91 "/workspaces/hve-core/.github/prompts/design-thinking": true,
92 "/workspaces/hve-core/.github/prompts/github": true,
93 "/workspaces/hve-core/.github/prompts/hve-core": true,
94 "/workspaces/hve-core/.github/prompts/security": true
95 },
96 "chat.instructionsFilesLocations": {
97 "/workspaces/hve-core/.github/instructions/ado": true,
98 "/workspaces/hve-core/.github/instructions/coding-standards": true,
99 "/workspaces/hve-core/.github/instructions/design-thinking": true,
100 "/workspaces/hve-core/.github/instructions/github": true,
101 "/workspaces/hve-core/.github/instructions/hve-core": true,
102 "/workspaces/hve-core/.github/instructions/shared": true
103 },
104 "chat.agentSkillsLocations": {
105 "/workspaces/hve-core/.github/skills": true,
106 "/workspaces/hve-core/.github/skills/shared": true,
107 "/workspaces/hve-core/.github/skills/coding-standards": true
108 }
109 }
110 }
111 }
112}
113```
114
115### Step 2: Commit and Push
116
117```bash
118git add .devcontainer/devcontainer.json
119git commit -m "feat: add HVE Core support for Codespaces"
120git push
121```
122
123### Step 3: Create or Rebuild Codespace
124
125* Create a new Codespace from the updated branch
126* Rebuild an existing Codespace (`Ctrl+Shift+P` → "Codespaces: Rebuild Container")
127
128### Step 4: Validate Installation
129
1301. Open GitHub Copilot Chat (`Ctrl+Alt+I`)
1312. Click the agent picker dropdown
1323. Verify HVE Core agents appear (task-planner, task-researcher, prompt-builder)
133
134## Complete Configuration Examples
135
136### Minimal Configuration
137
138```jsonc
139{
140 "name": "HVE Core Enabled",
141 "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
142
143 "postCreateCommand": "[ -d /workspaces/hve-core ] || git clone --depth 1 https://github.com/microsoft/hve-core.git /workspaces/hve-core",
144
145 "customizations": {
146 "vscode": {
147 "settings": {
148 "chat.agentFilesLocations": {
149 "/workspaces/hve-core/.github/agents/ado": true,
150 "/workspaces/hve-core/.github/agents/data-science": true,
151 "/workspaces/hve-core/.github/agents/design-thinking": true,
152 "/workspaces/hve-core/.github/agents/github": true,
153 "/workspaces/hve-core/.github/agents/project-planning": true,
154 "/workspaces/hve-core/.github/agents/hve-core": true,
155 "/workspaces/hve-core/.github/agents/hve-core/subagents": true,
156 "/workspaces/hve-core/.github/agents/security": true
157 },
158 "chat.promptFilesLocations": {
159 "/workspaces/hve-core/.github/prompts/ado": true,
160 "/workspaces/hve-core/.github/prompts/design-thinking": true,
161 "/workspaces/hve-core/.github/prompts/github": true,
162 "/workspaces/hve-core/.github/prompts/hve-core": true,
163 "/workspaces/hve-core/.github/prompts/security": true
164 },
165 "chat.instructionsFilesLocations": {
166 "/workspaces/hve-core/.github/instructions/ado": true,
167 "/workspaces/hve-core/.github/instructions/coding-standards": true,
168 "/workspaces/hve-core/.github/instructions/design-thinking": true,
169 "/workspaces/hve-core/.github/instructions/github": true,
170 "/workspaces/hve-core/.github/instructions/hve-core": true,
171 "/workspaces/hve-core/.github/instructions/shared": true
172 },
173 "chat.agentSkillsLocations": {
174 "/workspaces/hve-core/.github/skills": true,
175 "/workspaces/hve-core/.github/skills/shared": true,
176 "/workspaces/hve-core/.github/skills/coding-standards": true
177 }
178 }
179 }
180 }
181}
182```
183
184### Full-Featured Configuration
185
186```jsonc
187{
188 "name": "HVE Core Development Environment",
189 "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
190
191 "features": {
192 "ghcr.io/devcontainers/features/git:1": {},
193 "ghcr.io/devcontainers/features/github-cli:1": {}
194 },
195
196 "postCreateCommand": {
197 "clone-hve-core": "if [ ! -d /workspaces/hve-core ]; then git clone --depth 1 https://github.com/microsoft/hve-core.git /workspaces/hve-core && echo '✅ HVE Core cloned'; else echo '✅ HVE Core present'; fi",
198 "verify": "test -d /workspaces/hve-core/.github/agents && echo '✅ Verified' || echo '⚠️ Missing'"
199 },
200
201 "updateContentCommand": "cd /workspaces/hve-core && git pull --ff-only 2>/dev/null || echo 'Update skipped'",
202
203 "customizations": {
204 "vscode": {
205 "settings": {
206 "chat.promptFilesLocations": {
207 "/workspaces/hve-core/.github/prompts/ado": true,
208 "/workspaces/hve-core/.github/prompts/design-thinking": true,
209 "/workspaces/hve-core/.github/prompts/github": true,
210 "/workspaces/hve-core/.github/prompts/hve-core": true,
211 "/workspaces/hve-core/.github/prompts/security": true,
212 ".github/prompts": true
213 },
214 "chat.instructionsFilesLocations": {
215 "/workspaces/hve-core/.github/instructions/ado": true,
216 "/workspaces/hve-core/.github/instructions/coding-standards": true,
217 "/workspaces/hve-core/.github/instructions/design-thinking": true,
218 "/workspaces/hve-core/.github/instructions/github": true,
219 "/workspaces/hve-core/.github/instructions/hve-core": true,
220 "/workspaces/hve-core/.github/instructions/shared": true,
221 ".github/instructions": true
222 },
223 "chat.agentFilesLocations": {
224 "/workspaces/hve-core/.github/agents/ado": true,
225 "/workspaces/hve-core/.github/agents/data-science": true,
226 "/workspaces/hve-core/.github/agents/design-thinking": true,
227 "/workspaces/hve-core/.github/agents/github": true,
228 "/workspaces/hve-core/.github/agents/project-planning": true,
229 "/workspaces/hve-core/.github/agents/hve-core": true,
230 "/workspaces/hve-core/.github/agents/hve-core/subagents": true,
231 "/workspaces/hve-core/.github/agents/security": true,
232 ".github/agents": true
233 },
234 "chat.agentSkillsLocations": {
235 "/workspaces/hve-core/.github/skills": true,
236 "/workspaces/hve-core/.github/skills/shared": true,
237 "/workspaces/hve-core/.github/skills/coding-standards": true,
238 ".github/skills": true
239 }
240 }
241 }
242 }
243}
244```
245
246### Dual-Environment (Local + Codespaces)
247
248For projects needing HVE Core in both local devcontainers and Codespaces:
249
250```jsonc
251{
252 "name": "HVE Core (Local + Codespaces)",
253 "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
254
255 // Clone if not already present (Codespaces path)
256 "postCreateCommand": "[ -d /workspaces/hve-core ] || git clone --depth 1 https://github.com/microsoft/hve-core.git /workspaces/hve-core",
257
258 // Local only: mount peer directory (silently fails in Codespaces)
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 // Both paths - VS Code ignores non-existent paths
267 "chat.promptFilesLocations": {
268 "/workspaces/hve-core/.github/prompts/ado": true,
269 "/workspaces/hve-core/.github/prompts/design-thinking": true,
270 "/workspaces/hve-core/.github/prompts/github": true,
271 "/workspaces/hve-core/.github/prompts/hve-core": true,
272 "/workspaces/hve-core/.github/prompts/security": true,
273 "../hve-core/.github/prompts/ado": true,
274 "../hve-core/.github/prompts/design-thinking": true,
275 "../hve-core/.github/prompts/github": true,
276 "../hve-core/.github/prompts/hve-core": true,
277 "../hve-core/.github/prompts/security": true
278 },
279 "chat.instructionsFilesLocations": {
280 "/workspaces/hve-core/.github/instructions/ado": true,
281 "/workspaces/hve-core/.github/instructions/coding-standards": true,
282 "/workspaces/hve-core/.github/instructions/design-thinking": true,
283 "/workspaces/hve-core/.github/instructions/github": true,
284 "/workspaces/hve-core/.github/instructions/hve-core": true,
285 "/workspaces/hve-core/.github/instructions/shared": true,
286 "../hve-core/.github/instructions/ado": true,
287 "../hve-core/.github/instructions/coding-standards": true,
288 "../hve-core/.github/instructions/design-thinking": true,
289 "../hve-core/.github/instructions/github": true,
290 "../hve-core/.github/instructions/hve-core": true,
291 "../hve-core/.github/instructions/shared": true
292 },
293 "chat.agentFilesLocations": {
294 "/workspaces/hve-core/.github/agents/ado": true,
295 "/workspaces/hve-core/.github/agents/data-science": true,
296 "/workspaces/hve-core/.github/agents/design-thinking": true,
297 "/workspaces/hve-core/.github/agents/github": true,
298 "/workspaces/hve-core/.github/agents/project-planning": true,
299 "/workspaces/hve-core/.github/agents/hve-core": true,
300 "/workspaces/hve-core/.github/agents/hve-core/subagents": true,
301 "/workspaces/hve-core/.github/agents/security": true,
302 "../hve-core/.github/agents/ado": true,
303 "../hve-core/.github/agents/data-science": true,
304 "../hve-core/.github/agents/design-thinking": true,
305 "../hve-core/.github/agents/github": true,
306 "../hve-core/.github/agents/project-planning": true,
307 "../hve-core/.github/agents/hve-core": true,
308 "../hve-core/.github/agents/hve-core/subagents": true,
309 "../hve-core/.github/agents/security": true
310 },
311 "chat.agentSkillsLocations": {
312 "/workspaces/hve-core/.github/skills": true,
313 "/workspaces/hve-core/.github/skills/shared": true,
314 "/workspaces/hve-core/.github/skills/coding-standards": true,
315 "../hve-core/.github/skills": true,
316 "../hve-core/.github/skills/shared": true
317 }
318 }
319 }
320 }
321}
322```
323
324## Updating HVE Core
325
326### Manual Update
327
328```bash
329cd /workspaces/hve-core
330git pull
331```
332
333### Auto-Update on Codespace Start
334
335Add `updateContentCommand` to your devcontainer.json:
336
337```jsonc
338{
339 "updateContentCommand": "cd /workspaces/hve-core && git pull --ff-only 2>/dev/null || true"
340}
341```
342
343This runs when the Codespace starts (not on every terminal open).
344
345### Force Fresh Clone
346
347To always get the latest version on rebuild:
348
349```jsonc
350{
351 "postCreateCommand": "rm -rf /workspaces/hve-core && git clone --depth 1 https://github.com/microsoft/hve-core.git /workspaces/hve-core"
352}
353```
354
355**Warning:** This removes any local changes on every rebuild.
356
357## Troubleshooting
358
359### Agents Not Appearing
360
361#### Check HVE Core was cloned
362
363```bash
364ls /workspaces/hve-core/.github/agents
365```
366
367#### Check postCreateCommand ran
368
369Look at the Codespace creation log for clone output or errors.
370
371### Clone Failed During Creation
372
373**Network issues:** Try rebuilding the Codespace.
374
375**GitHub rate limiting:** Ensure you're authenticated:
376
377```bash
378gh auth status
379```
380
381### Settings Not Applied
382
383#### Check devcontainer.json paths
384
385Settings must use absolute paths (`/workspaces/hve-core/...`).
386
387#### Verify settings in VS Code
388
3891. Open Command Palette (`Ctrl+Shift+P`)
3902. Type "Preferences: Open User Settings (JSON)"
3913. Check if settings are present
392
393### Codespace Rebuild Doesn't Update HVE Core
394
395The clone command skips if the folder exists. Force update:
396
397```bash
398cd /workspaces/hve-core
399git pull
400```
401
402Or modify postCreateCommand to always pull (see Auto-Update section).
403
404## Limitations
405
406| Aspect | Status |
407|---------------------|-------------------------------------------|
408| Codespaces | ✅ Designed for this |
409| Local devcontainers | ⚠️ Works but consider other methods |
410| Team sharing | ✅ Auto-setup for all contributors |
411| Portable paths | ⚠️ Absolute paths only |
412| Version pinning | ⚠️ Modify clone command for specific tag |
413| Offline support | ❌ Requires network during creation |
414| Setup complexity | ✅ Low (just devcontainer.json) |
415
416## Version Pinning
417
418To pin to a specific version:
419
420```jsonc
421{
422 "postCreateCommand": "[ -d /workspaces/hve-core ] || git clone --depth 1 --branch v1.0.0 https://github.com/microsoft/hve-core.git /workspaces/hve-core"
423}
424```
425
426Replace `v1.0.0` with your desired version tag.
427
428## Next Steps
429
430* [Your First Workflow](../first-workflow.md) - Try HVE Core with a real task
431* [Multi-Root Workspace](multi-root.md) - For dual local + Codespaces support
432* [Submodule](submodule.md) - For team version control
433
434---
435
436<!-- markdownlint-disable MD036 -->
437*🤖 Crafted with precision by ✨Copilot following brilliant human instruction,
438then carefully refined by our team of discerning human reviewers.*
439<!-- markdownlint-enable MD036 -->
440