Manual setup checklist

SwarmCraft Setup is the supported default for macOS and Windows. This checklist reaches the same readiness outcome without Setup's automated detection, signature checks, preservation rules, or repair plan.

Use this manual path when your organisation manages software distribution, Setup is unavailable for the machine, or you deliberately want to own each vendor installation.

You own vendor selection, signatures, checksums, elevation, updates, system changes, and repair on this path.

1. Confirm the platform

Use a supported macOS release on Apple silicon or Intel, or x86-64 Windows 11 23H2 or later. If your organisation manages the machine, follow its approved software catalogue and verification policy.

2. Install the foundation

Install and verify these vendor-owned tools:

1. Visual Studio Code
2. Git
3. GitHub CLI
4. Docker Desktop, only when the project requires containers

Keep vendor update mechanisms enabled. SwarmCraft does not replace VS Code, GitHub CLI, Git, Docker, or Marketplace update ownership.

Verify each required command before continuing:

code --version
git --version
gh --version

3. Create the dedicated profile and install the extension

Create a VS Code profile named SwarmCraft. Install only the exact extension ID SwarmCraft.swarmcraft-vscode-extension into that profile.

Open the Extensions view in VS Code, search for the exact ID SwarmCraft.swarmcraft-vscode-extension, confirm the publisher is SwarmCraft, and select Install.

You can also use the SwarmCraft Marketplace listing or this command:

code --profile SwarmCraft --install-extension SwarmCraft.swarmcraft-vscode-extension

For managed offline installation, use only the VSIX and checksum supplied through your organisation's approved release process.

4. Connect GitHub CLI

Start GitHub CLI browser authentication:

gh auth login --hostname github.com --git-protocol https --web
gh auth setup-git --hostname github.com
gh auth status --hostname github.com

Use the browser opened by GitHub CLI. Do not put a token in the command or share the one-time browser code. Confirm gh auth status reports the intended active account and secure credential storage.

5. Set commit identity separately

GitHub authentication does not set the author recorded on commits. Review the current values, then set only what you intend to use:

git config --global user.name
git config --global user.email
git config --global user.name "Your commit name"
git config --global user.email "your-commit-email@example.com"

6. Open the token-free handoff

Open the dedicated profile and the extension welcome route:

code --profile SwarmCraft "vscode://SwarmCraft.swarmcraft-vscode-extension/setup/welcome"

The URI contains no token, browser code, account data, or repository path.

7. Confirm readiness and sign in

Confirm that:

• VS Code opened the SwarmCraft profile
• the SwarmCraft extension is installed and its view opens
• git --version and gh auth status succeed
• commit name and email are configured
• Docker is available only if the project requires containers

Then run SwarmCraft: Sign In and complete SwarmCraft account sign-in in the browser.

Keep account and repository grants separate

SwarmCraft account sign-in happens in your browser through AAA V2. GitHub repository access remains a separate gh auth login grant stored by GitHub CLI. Signing in to SwarmCraft with GitHub does not give the extension repository access, and repository access does not create a SwarmCraft session.

SwarmCraft browser sign-in, GitHub CLI repository access, and Git commit identity are three separate checks. Continue with Sign in and secure your account, then choose a discovery route or connect a ready project.

If a check fails, use Setup and connection recovery. Install the one-shot CLI only after this foundation works and only when you want experienced terminal delivery.