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

435lines · 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 }
108 }
109 }
110 }
111}
112```
113
114### Step 2: Commit and Push
115
116```bash
117git add .devcontainer/devcontainer.json
118git commit -m "feat: add HVE Core support for Codespaces"
119git push
120```
121
122### Step 3: Create or Rebuild Codespace
123
124* Create a new Codespace from the updated branch
125* Rebuild an existing Codespace (`Ctrl+Shift+P` → "Codespaces: Rebuild Container")
126
127### Step 4: Validate Installation
128
1291. Open GitHub Copilot Chat (`Ctrl+Alt+I`)
1302. Click the agent picker dropdown
1313. Verify HVE Core agents appear (task-planner, task-researcher, prompt-builder)
132
133## Complete Configuration Examples
134
135### Minimal Configuration
136
137```jsonc
138{
139 "name": "HVE Core Enabled",
140 "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
141
142 "postCreateCommand": "[ -d /workspaces/hve-core ] || git clone --depth 1 https://github.com/microsoft/hve-core.git /workspaces/hve-core",
143
144 "customizations": {
145 "vscode": {
146 "settings": {
147 "chat.agentFilesLocations": {
148 "/workspaces/hve-core/.github/agents/ado": true,
149 "/workspaces/hve-core/.github/agents/data-science": true,
150 "/workspaces/hve-core/.github/agents/design-thinking": true,
151 "/workspaces/hve-core/.github/agents/github": true,
152 "/workspaces/hve-core/.github/agents/project-planning": true,
153 "/workspaces/hve-core/.github/agents/hve-core": true,
154 "/workspaces/hve-core/.github/agents/hve-core/subagents": true,
155 "/workspaces/hve-core/.github/agents/security": true
156 },
157 "chat.promptFilesLocations": {
158 "/workspaces/hve-core/.github/prompts/ado": true,
159 "/workspaces/hve-core/.github/prompts/design-thinking": true,
160 "/workspaces/hve-core/.github/prompts/github": true,
161 "/workspaces/hve-core/.github/prompts/hve-core": true,
162 "/workspaces/hve-core/.github/prompts/security": true
163 },
164 "chat.instructionsFilesLocations": {
165 "/workspaces/hve-core/.github/instructions/ado": true,
166 "/workspaces/hve-core/.github/instructions/coding-standards": true,
167 "/workspaces/hve-core/.github/instructions/design-thinking": true,
168 "/workspaces/hve-core/.github/instructions/github": true,
169 "/workspaces/hve-core/.github/instructions/hve-core": true,
170 "/workspaces/hve-core/.github/instructions/shared": true
171 },
172 "chat.agentSkillsLocations": {
173 "/workspaces/hve-core/.github/skills": true,
174 "/workspaces/hve-core/.github/skills/shared": true
175 }
176 }
177 }
178 }
179}
180```
181
182### Full-Featured Configuration
183
184```jsonc
185{
186 "name": "HVE Core Development Environment",
187 "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
188
189 "features": {
190 "ghcr.io/devcontainers/features/git:1": {},
191 "ghcr.io/devcontainers/features/github-cli:1": {}
192 },
193
194 "postCreateCommand": {
195 "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",
196 "verify": "test -d /workspaces/hve-core/.github/agents && echo '✅ Verified' || echo '⚠️ Missing'"
197 },
198
199 "updateContentCommand": "cd /workspaces/hve-core && git pull --ff-only 2>/dev/null || echo 'Update skipped'",
200
201 "customizations": {
202 "vscode": {
203 "settings": {
204 "chat.promptFilesLocations": {
205 "/workspaces/hve-core/.github/prompts/ado": true,
206 "/workspaces/hve-core/.github/prompts/design-thinking": true,
207 "/workspaces/hve-core/.github/prompts/github": true,
208 "/workspaces/hve-core/.github/prompts/hve-core": true,
209 "/workspaces/hve-core/.github/prompts/security": true,
210 ".github/prompts": true
211 },
212 "chat.instructionsFilesLocations": {
213 "/workspaces/hve-core/.github/instructions/ado": true,
214 "/workspaces/hve-core/.github/instructions/coding-standards": true,
215 "/workspaces/hve-core/.github/instructions/design-thinking": true,
216 "/workspaces/hve-core/.github/instructions/github": true,
217 "/workspaces/hve-core/.github/instructions/hve-core": true,
218 "/workspaces/hve-core/.github/instructions/shared": true,
219 ".github/instructions": true
220 },
221 "chat.agentFilesLocations": {
222 "/workspaces/hve-core/.github/agents/ado": true,
223 "/workspaces/hve-core/.github/agents/data-science": true,
224 "/workspaces/hve-core/.github/agents/design-thinking": true,
225 "/workspaces/hve-core/.github/agents/github": true,
226 "/workspaces/hve-core/.github/agents/project-planning": true,
227 "/workspaces/hve-core/.github/agents/hve-core": true,
228 "/workspaces/hve-core/.github/agents/hve-core/subagents": true,
229 "/workspaces/hve-core/.github/agents/security": true,
230 ".github/agents": true
231 },
232 "chat.agentSkillsLocations": {
233 "/workspaces/hve-core/.github/skills": true,
234 "/workspaces/hve-core/.github/skills/shared": true,
235 ".github/skills": true
236 }
237 }
238 }
239 }
240}
241```
242
243### Dual-Environment (Local + Codespaces)
244
245For projects needing HVE Core in both local devcontainers and Codespaces:
246
247```jsonc
248{
249 "name": "HVE Core (Local + Codespaces)",
250 "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
251
252 // Clone if not already present (Codespaces path)
253 "postCreateCommand": "[ -d /workspaces/hve-core ] || git clone --depth 1 https://github.com/microsoft/hve-core.git /workspaces/hve-core",
254
255 // Local only: mount peer directory (silently fails in Codespaces)
256 "mounts": [
257 "source=${localWorkspaceFolder}/../hve-core,target=/workspaces/hve-core,type=bind,readonly=true,consistency=cached"
258 ],
259
260 "customizations": {
261 "vscode": {
262 "settings": {
263 // Both paths - VS Code ignores non-existent paths
264 "chat.promptFilesLocations": {
265 "/workspaces/hve-core/.github/prompts/ado": true,
266 "/workspaces/hve-core/.github/prompts/design-thinking": true,
267 "/workspaces/hve-core/.github/prompts/github": true,
268 "/workspaces/hve-core/.github/prompts/hve-core": true,
269 "/workspaces/hve-core/.github/prompts/security": true,
270 "../hve-core/.github/prompts/ado": true,
271 "../hve-core/.github/prompts/design-thinking": true,
272 "../hve-core/.github/prompts/github": true,
273 "../hve-core/.github/prompts/hve-core": true,
274 "../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 "../hve-core/.github/instructions/ado": true,
284 "../hve-core/.github/instructions/coding-standards": true,
285 "../hve-core/.github/instructions/design-thinking": true,
286 "../hve-core/.github/instructions/github": true,
287 "../hve-core/.github/instructions/hve-core": true,
288 "../hve-core/.github/instructions/shared": true
289 },
290 "chat.agentFilesLocations": {
291 "/workspaces/hve-core/.github/agents/ado": true,
292 "/workspaces/hve-core/.github/agents/data-science": true,
293 "/workspaces/hve-core/.github/agents/design-thinking": true,
294 "/workspaces/hve-core/.github/agents/github": true,
295 "/workspaces/hve-core/.github/agents/project-planning": true,
296 "/workspaces/hve-core/.github/agents/hve-core": true,
297 "/workspaces/hve-core/.github/agents/hve-core/subagents": true,
298 "/workspaces/hve-core/.github/agents/security": true,
299 "../hve-core/.github/agents/ado": true,
300 "../hve-core/.github/agents/data-science": true,
301 "../hve-core/.github/agents/design-thinking": true,
302 "../hve-core/.github/agents/github": true,
303 "../hve-core/.github/agents/project-planning": true,
304 "../hve-core/.github/agents/hve-core": true,
305 "../hve-core/.github/agents/hve-core/subagents": true,
306 "../hve-core/.github/agents/security": true
307 },
308 "chat.agentSkillsLocations": {
309 "/workspaces/hve-core/.github/skills": true,
310 "/workspaces/hve-core/.github/skills/shared": true,
311 "../hve-core/.github/skills": true,
312 "../hve-core/.github/skills/shared": true
313 }
314 }
315 }
316 }
317}
318```
319
320## Updating HVE Core
321
322### Manual Update
323
324```bash
325cd /workspaces/hve-core
326git pull
327```
328
329### Auto-Update on Codespace Start
330
331Add `updateContentCommand` to your devcontainer.json:
332
333```jsonc
334{
335 "updateContentCommand": "cd /workspaces/hve-core && git pull --ff-only 2>/dev/null || true"
336}
337```
338
339This runs when the Codespace starts (not on every terminal open).
340
341### Force Fresh Clone
342
343To always get the latest version on rebuild:
344
345```jsonc
346{
347 "postCreateCommand": "rm -rf /workspaces/hve-core && git clone --depth 1 https://github.com/microsoft/hve-core.git /workspaces/hve-core"
348}
349```
350
351**Warning:** This removes any local changes on every rebuild.
352
353## Troubleshooting
354
355### Agents Not Appearing
356
357#### Check HVE Core was cloned
358
359```bash
360ls /workspaces/hve-core/.github/agents
361```
362
363#### Check postCreateCommand ran
364
365Look at the Codespace creation log for clone output or errors.
366
367### Clone Failed During Creation
368
369**Network issues:** Try rebuilding the Codespace.
370
371**GitHub rate limiting:** Ensure you're authenticated:
372
373```bash
374gh auth status
375```
376
377### Settings Not Applied
378
379#### Check devcontainer.json paths
380
381Settings must use absolute paths (`/workspaces/hve-core/...`).
382
383#### Verify settings in VS Code
384
3851. Open Command Palette (`Ctrl+Shift+P`)
3862. Type "Preferences: Open User Settings (JSON)"
3873. Check if settings are present
388
389### Codespace Rebuild Doesn't Update HVE Core
390
391The clone command skips if the folder exists. Force update:
392
393```bash
394cd /workspaces/hve-core
395git pull
396```
397
398Or modify postCreateCommand to always pull (see Auto-Update section).
399
400## Limitations
401
402| Aspect | Status |
403|---------------------|-------------------------------------------|
404| Codespaces | ✅ Designed for this |
405| Local devcontainers | ⚠️ Works but consider other methods |
406| Team sharing | ✅ Auto-setup for all contributors |
407| Portable paths | ⚠️ Absolute paths only |
408| Version pinning | ⚠️ Modify clone command for specific tag |
409| Offline support | ❌ Requires network during creation |
410| Setup complexity | ✅ Low (just devcontainer.json) |
411
412## Version Pinning
413
414To pin to a specific version:
415
416```jsonc
417{
418 "postCreateCommand": "[ -d /workspaces/hve-core ] || git clone --depth 1 --branch v1.0.0 https://github.com/microsoft/hve-core.git /workspaces/hve-core"
419}
420```
421
422Replace `v1.0.0` with your desired version tag.
423
424## Next Steps
425
426* [Your First Workflow](../first-workflow.md) - Try HVE Core with a real task
427* [Multi-Root Workspace](multi-root.md) - For dual local + Codespaces support
428* [Submodule](submodule.md) - For team version control
429
430---
431
432<!-- markdownlint-disable MD036 -->
433*🤖 Crafted with precision by ✨Copilot following brilliant human instruction,
434then carefully refined by our team of discerning human reviewers.*
435<!-- markdownlint-enable MD036 -->
436