hve-core/docs/getting-started/methods/codespaces.md at main · microsoft/hve-core

title

GitHub Codespaces Installation

description

Install HVE Core in GitHub Codespaces using postCreateCommand

sidebar_position

author

Microsoft

ms.date

2026-10-02

ms.topic

how-to

keywords

codespaces

installation

github copilot

postCreateCommand

cloud development

estimated_reading_time

GitHub 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.

When to Use This Method

✅ Use this when:

Your project runs exclusively in Codespaces
You want automatic HVE Core setup for all users
You need zero-config onboarding for contributors

❌ Consider alternatives when:

You also need local devcontainer support → Multi-Root Workspace
Your team needs version control → Submodule
You're using local VS Code only → Peer Clone

Why Other Methods Don't Work in Codespaces

Feature	Local Devcontainer	GitHub Codespaces
`${localWorkspaceFolder}`	✅ Resolves to host	❌ Not available
Bind mounts to host	✅ Full support	❌ No host access
Persistent storage	Host filesystem	`/workspaces` only
User settings modification	✅ Via file system	❌ Only via Settings Sync¹

How It Works

Codespaces has a specific storage model:

/
├── workspaces/              # ✅ PERSISTENT - survives stops/restarts
│   ├── your-repo/           # Your cloned repository
│   └── hve-core/            # 👈 HVE Core goes here
├── home/codespace/          # ⚠️ Semi-persistent (survives stops, not rebuilds)
└── <system-dirs>/           # ❌ Not persistent

The postCreateCommand clones HVE Core into /workspaces/hve-core where it persists across Codespace sessions.

Quick Start

Install the VS Code extension for the fastest setup. For guided installation-method selection, MCP configuration, or selective clone adoption, ask an agent to use the included hve-core-installer skill. Use the manual steps below for direct configuration.

Manual Setup

Step 1: Update devcontainer.json

Add the clone command and VS Code settings:

{
  "name": "My Project with HVE Core",
  "image": "mcr.microsoft.com/devcontainers/base:ubuntu",

  "postCreateCommand": "[ -d /workspaces/hve-core ] || git clone --depth 1 https://github.com/microsoft/hve-core.git /workspaces/hve-core",

  "customizations": {
    "vscode": {
      "settings": {
        "chat.agentFilesLocations": {
          "/workspaces/hve-core/.github/agents/ado": true,
          "/workspaces/hve-core/.github/agents/data-science": true,
          "/workspaces/hve-core/.github/agents/design-thinking": true,
          "/workspaces/hve-core/.github/agents/github": true,
          "/workspaces/hve-core/.github/agents/project-planning": true,
          "/workspaces/hve-core/.github/agents/hve-core": true,
          "/workspaces/hve-core/.github/agents/hve-core/subagents": true,
          "/workspaces/hve-core/.github/agents/security": true
        },
        "chat.instructionsFilesLocations": {
          "/workspaces/hve-core/.github/instructions/ado": true,
          "/workspaces/hve-core/.github/instructions/coding-standards": true,
          "/workspaces/hve-core/.github/instructions/github": true,
          "/workspaces/hve-core/.github/instructions/hve-core": true,
          "/workspaces/hve-core/.github/instructions/shared": true
        },
        "chat.agentSkillsLocations": {
          "/workspaces/hve-core/.github/skills": true,
          "/workspaces/hve-core/.github/skills/accessibility": true,
          "/workspaces/hve-core/.github/skills/shared": true,
          "/workspaces/hve-core/.github/skills/coding-standards": true,
          "/workspaces/hve-core/.github/skills/data-science": true,
          "/workspaces/hve-core/.github/skills/design-thinking": true,
          "/workspaces/hve-core/.github/skills/hve-core": true,
          "/workspaces/hve-core/.github/skills/installer": true,
          "/workspaces/hve-core/.github/skills/project-planning": true,
          "/workspaces/hve-core/.github/skills/rai": true,
          "/workspaces/hve-core/.github/skills/rpi": true,
          "/workspaces/hve-core/.github/skills/security": true
        }
      }
    }
  }
}

Step 2: Commit and Push

git add .devcontainer/devcontainer.json
git commit -m "feat: add HVE Core support for Codespaces"
git push

Step 3: Create or Rebuild Codespace

Create a new Codespace from the updated branch
Rebuild an existing Codespace (Ctrl+Shift+P → "Codespaces: Rebuild Container")

Step 4: Validate Installation

Open GitHub Copilot Chat (Ctrl+Alt+I)
Click the agent picker dropdown
Verify RPI Agent and Documentation appear, then confirm /rpi-research is available

Complete Configuration Examples

Minimal Configuration

{
  "name": "HVE Core Enabled",
  "image": "mcr.microsoft.com/devcontainers/base:ubuntu",

  "postCreateCommand": "[ -d /workspaces/hve-core ] || git clone --depth 1 https://github.com/microsoft/hve-core.git /workspaces/hve-core",

  "customizations": {
    "vscode": {
      "settings": {
        "chat.agentFilesLocations": {
          "/workspaces/hve-core/.github/agents/ado": true,
          "/workspaces/hve-core/.github/agents/data-science": true,
          "/workspaces/hve-core/.github/agents/design-thinking": true,
          "/workspaces/hve-core/.github/agents/github": true,
          "/workspaces/hve-core/.github/agents/project-planning": true,
          "/workspaces/hve-core/.github/agents/hve-core": true,
          "/workspaces/hve-core/.github/agents/hve-core/subagents": true,
          "/workspaces/hve-core/.github/agents/security": true
        },
        "chat.instructionsFilesLocations": {
          "/workspaces/hve-core/.github/instructions/ado": true,
          "/workspaces/hve-core/.github/instructions/coding-standards": true,
          "/workspaces/hve-core/.github/instructions/github": true,
          "/workspaces/hve-core/.github/instructions/hve-core": true,
          "/workspaces/hve-core/.github/instructions/shared": true
        },
        "chat.agentSkillsLocations": {
          "/workspaces/hve-core/.github/skills": true,
          "/workspaces/hve-core/.github/skills/accessibility": true,
          "/workspaces/hve-core/.github/skills/shared": true,
          "/workspaces/hve-core/.github/skills/coding-standards": true,
          "/workspaces/hve-core/.github/skills/data-science": true,
          "/workspaces/hve-core/.github/skills/design-thinking": true,
          "/workspaces/hve-core/.github/skills/hve-core": true,
          "/workspaces/hve-core/.github/skills/installer": true,
          "/workspaces/hve-core/.github/skills/project-planning": true,
          "/workspaces/hve-core/.github/skills/rai": true,
          "/workspaces/hve-core/.github/skills/rpi": true,
          "/workspaces/hve-core/.github/skills/security": true
        }
      }
    }
  }
}

Full-Featured Configuration

{
  "name": "HVE Core Development Environment",
  "image": "mcr.microsoft.com/devcontainers/base:ubuntu",

  "features": {
    "ghcr.io/devcontainers/features/git:1": {},
    "ghcr.io/devcontainers/features/github-cli:1": {}
  },

  "postCreateCommand": {
    "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",
    "verify": "test -d /workspaces/hve-core/.github/agents && echo '✅ Verified' || echo '⚠️ Missing'"
  },

  "updateContentCommand": "cd /workspaces/hve-core && git pull --ff-only 2>/dev/null || echo 'Update skipped'",

  "customizations": {
    "vscode": {
      "settings": {
        "chat.instructionsFilesLocations": {
          "/workspaces/hve-core/.github/instructions/ado": true,
          "/workspaces/hve-core/.github/instructions/coding-standards": true,
          "/workspaces/hve-core/.github/instructions/github": true,
          "/workspaces/hve-core/.github/instructions/hve-core": true,
          "/workspaces/hve-core/.github/instructions/shared": true,
          ".github/instructions": true
        },
        "chat.agentFilesLocations": {
          "/workspaces/hve-core/.github/agents/ado": true,
          "/workspaces/hve-core/.github/agents/data-science": true,
          "/workspaces/hve-core/.github/agents/design-thinking": true,
          "/workspaces/hve-core/.github/agents/github": true,
          "/workspaces/hve-core/.github/agents/project-planning": true,
          "/workspaces/hve-core/.github/agents/hve-core": true,
          "/workspaces/hve-core/.github/agents/hve-core/subagents": true,
          "/workspaces/hve-core/.github/agents/security": true,
          ".github/agents": true
        },
        "chat.agentSkillsLocations": {
          "/workspaces/hve-core/.github/skills": true,
          "/workspaces/hve-core/.github/skills/accessibility": true,
          "/workspaces/hve-core/.github/skills/shared": true,
          "/workspaces/hve-core/.github/skills/coding-standards": true,
          "/workspaces/hve-core/.github/skills/data-science": true,
          "/workspaces/hve-core/.github/skills/design-thinking": true,
          "/workspaces/hve-core/.github/skills/hve-core": true,
          "/workspaces/hve-core/.github/skills/installer": true,
          "/workspaces/hve-core/.github/skills/project-planning": true,
          "/workspaces/hve-core/.github/skills/rai": true,
          "/workspaces/hve-core/.github/skills/rpi": true,
          "/workspaces/hve-core/.github/skills/security": true,
          ".github/skills": true
        }
      }
    }
  }
}

Dual-Environment (Local + Codespaces)

For projects needing HVE Core in both local devcontainers and Codespaces:

{
  "name": "HVE Core (Local + Codespaces)",
  "image": "mcr.microsoft.com/devcontainers/base:ubuntu",

  // Clone if not already present (Codespaces path)
  "postCreateCommand": "[ -d /workspaces/hve-core ] || git clone --depth 1 https://github.com/microsoft/hve-core.git /workspaces/hve-core",

  // Local only: mount peer directory (silently fails in Codespaces)
  "mounts": [
    "source=${localWorkspaceFolder}/../hve-core,target=/workspaces/hve-core,type=bind,readonly=true,consistency=cached"
  ],

  "customizations": {
    "vscode": {
      "settings": {
        // Both paths - VS Code ignores non-existent paths
        "chat.instructionsFilesLocations": {
          "/workspaces/hve-core/.github/instructions/ado": true,
          "/workspaces/hve-core/.github/instructions/coding-standards": true,
          "/workspaces/hve-core/.github/instructions/github": true,
          "/workspaces/hve-core/.github/instructions/hve-core": true,
          "/workspaces/hve-core/.github/instructions/shared": true,
          "../hve-core/.github/instructions/ado": true,
          "../hve-core/.github/instructions/coding-standards": true,
          "../hve-core/.github/instructions/github": true,
          "../hve-core/.github/instructions/hve-core": true,
          "../hve-core/.github/instructions/shared": true
        },
        "chat.agentFilesLocations": {
          "/workspaces/hve-core/.github/agents/ado": true,
          "/workspaces/hve-core/.github/agents/data-science": true,
          "/workspaces/hve-core/.github/agents/design-thinking": true,
          "/workspaces/hve-core/.github/agents/github": true,
          "/workspaces/hve-core/.github/agents/project-planning": true,
          "/workspaces/hve-core/.github/agents/hve-core": true,
          "/workspaces/hve-core/.github/agents/hve-core/subagents": true,
          "/workspaces/hve-core/.github/agents/security": true,
          "../hve-core/.github/agents/ado": true,
          "../hve-core/.github/agents/data-science": true,
          "../hve-core/.github/agents/design-thinking": true,
          "../hve-core/.github/agents/github": true,
          "../hve-core/.github/agents/project-planning": true,
          "../hve-core/.github/agents/hve-core": true,
          "../hve-core/.github/agents/hve-core/subagents": true,
          "../hve-core/.github/agents/security": true
        },
        "chat.agentSkillsLocations": {
          "/workspaces/hve-core/.github/skills": true,
          "/workspaces/hve-core/.github/skills/accessibility": true,
          "/workspaces/hve-core/.github/skills/shared": true,
          "/workspaces/hve-core/.github/skills/coding-standards": true,
          "/workspaces/hve-core/.github/skills/data-science": true,
          "/workspaces/hve-core/.github/skills/design-thinking": true,
          "/workspaces/hve-core/.github/skills/hve-core": true,
          "/workspaces/hve-core/.github/skills/installer": true,
          "/workspaces/hve-core/.github/skills/project-planning": true,
          "/workspaces/hve-core/.github/skills/rai": true,
          "/workspaces/hve-core/.github/skills/rpi": true,
          "/workspaces/hve-core/.github/skills/security": true,
          "../hve-core/.github/skills": true,
          "../hve-core/.github/skills/accessibility": true,
          "../hve-core/.github/skills/shared": true,
          "../hve-core/.github/skills/coding-standards": true,
          "../hve-core/.github/skills/data-science": true,
          "../hve-core/.github/skills/design-thinking": true,
          "../hve-core/.github/skills/hve-core": true,
          "../hve-core/.github/skills/installer": true,
          "../hve-core/.github/skills/project-planning": true,
          "../hve-core/.github/skills/rai": true,
          "../hve-core/.github/skills/rpi": true,
          "../hve-core/.github/skills/security": true
        }
      }
    }
  }
}

Updating HVE Core

Manual Update

cd /workspaces/hve-core
git pull

Auto-Update on Codespace Start

Add updateContentCommand to your devcontainer.json:

{
  "updateContentCommand": "cd /workspaces/hve-core && git pull --ff-only 2>/dev/null || true"
}

This runs when the Codespace starts (not on every terminal open).

Force Fresh Clone

To always get the latest version on rebuild:

{
  "postCreateCommand": "rm -rf /workspaces/hve-core && git clone --depth 1 https://github.com/microsoft/hve-core.git /workspaces/hve-core"
}

Warning: This removes any local changes on every rebuild.

Troubleshooting

Agents Not Appearing

Check HVE Core was cloned

ls /workspaces/hve-core/.github/agents

Check postCreateCommand ran

Look at the Codespace creation log for clone output or errors.

Clone Failed During Creation

Network issues: Try rebuilding the Codespace.

GitHub rate limiting: Ensure you're authenticated:

gh auth status

Settings Not Applied

Check devcontainer.json paths

Settings must use absolute paths (/workspaces/hve-core/...).

Verify settings in VS Code

Open Command Palette (Ctrl+Shift+P)
Type "Preferences: Open User Settings (JSON)"
Check if settings are present

Codespace Rebuild Doesn't Update HVE Core

The clone command skips if the folder exists. Force update:

cd /workspaces/hve-core
git pull

Or modify postCreateCommand to always pull (see Auto-Update section).

Limitations

Aspect	Status
Codespaces	✅ Designed for this
Local devcontainers	⚠️ Works but consider other methods
Team sharing	✅ Auto-setup for all contributors
Portable paths	⚠️ Absolute paths only
Version pinning	⚠️ Modify clone command for specific tag
Offline support	❌ Requires network during creation
Setup complexity	✅ Low (just devcontainer.json)

Version Pinning

To pin to a specific version:

{
  "postCreateCommand": "[ -d /workspaces/hve-core ] || git clone --depth 1 --branch v1.0.0 https://github.com/microsoft/hve-core.git /workspaces/hve-core"
}

Replace v1.0.0 with your desired version tag.

Next Steps

Your First Workflow - Try HVE Core with a real task
Multi-Root Workspace - For dual local + Codespaces support
Submodule - For team version control

🤖 Crafted with precision by ✨Copilot following brilliant human instruction, then carefully refined by our team of discerning human reviewers.

User-level settings require Settings Sync. Workspace/container-level settings can still be configured via devcontainer.json using customizations.vscode.settings. ↩

Navigation Menu

Repository navigation

codespaces.md

codespaces.md

When to Use This Method

Why Other Methods Don't Work in Codespaces

How It Works

Quick Start

Manual Setup

Step 1: Update devcontainer.json

Step 2: Commit and Push

Step 3: Create or Rebuild Codespace

Step 4: Validate Installation

Complete Configuration Examples

Minimal Configuration

Full-Featured Configuration

Dual-Environment (Local + Codespaces)

Updating HVE Core

Manual Update

Auto-Update on Codespace Start

Force Fresh Clone

Troubleshooting

Agents Not Appearing

Check HVE Core was cloned

Check postCreateCommand ran

Clone Failed During Creation

Settings Not Applied

Check devcontainer.json paths

Verify settings in VS Code

Codespace Rebuild Doesn't Update HVE Core

Limitations

Version Pinning

Next Steps

FilesExpand file tree

codespaces.md

Latest commit

History

codespaces.md

File metadata and controls

When to Use This Method

Why Other Methods Don't Work in Codespaces

How It Works

Quick Start

Manual Setup

Step 1: Update devcontainer.json

Step 2: Commit and Push

Step 3: Create or Rebuild Codespace

Step 4: Validate Installation

Complete Configuration Examples

Minimal Configuration

Full-Featured Configuration

Dual-Environment (Local + Codespaces)

Updating HVE Core

Manual Update

Auto-Update on Codespace Start

Force Fresh Clone

Troubleshooting

Agents Not Appearing

Check HVE Core was cloned

Check postCreateCommand ran

Clone Failed During Creation

Settings Not Applied

Check devcontainer.json paths

Verify settings in VS Code

Codespace Rebuild Doesn't Update HVE Core

Limitations

Version Pinning

Next Steps

Footnotes