> For the complete documentation index, see [llms.txt](https://skyforgeai.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://skyforgeai.gitbook.io/docs/start-here/installation.md).

# Installation

Install SkyForge, verify it runs, and fix the two environment issues that most commonly block a fresh install.

***

## Prerequisites

| Tool        | Version | Install                                                  |
| ----------- | ------- | -------------------------------------------------------- |
| **Node.js** | 22+     | [nodejs.org/en/download](https://nodejs.org/en/download) |

***

## Install

```bash
npm i -g @skyforgeai/skyforge@latest
```

Verify:

```bash
skyforge --version
```

### Updating

```bash
skyforge update
```

Runs `npm install -g @skyforgeai/skyforge@latest` for you — no need to remember the package name or re-type the npm command by hand. Update to a specific version instead of latest:

```bash
skyforge update <version>
```

> **Windows users:** If `skyforge` is not recognized after install, add `%APPDATA%\npm` to your system PATH:
>
> 1. Open **Start** → search **"Environment Variables"** → click **"Edit the system environment variables"**
> 2. Under **User variables**, select **Path** → click **Edit**
> 3. Click **New** and add: `%APPDATA%\npm` and `%APPDATA%\npm.cmd`
> 4. Click OK and restart your terminal
>
> **PowerShell only — if still not recognized after above:**
>
> **Option 1 — current session only (quick test):**
>
> ```powershell
> $env:PATH += ";$(npm prefix -g)"
> skyforge --version
> ```
>
> **Option 2 — permanent fix:**
>
> ```powershell
> $npmPath = npm prefix -g
> [Environment]::SetEnvironmentVariable("PATH", $env:PATH + ";$npmPath", "User")
> ```
>
> Restart PowerShell after running this.
>
> **Option 3 — if execution policy blocks scripts:**
>
> ```powershell
> Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
> ```
>
> Restart PowerShell and try again.

***

## Check directory access

SkyForge needs read/write access to these directories. Run the check for your platform **before** starting SkyForge — permission errors cause silent failures in analytics and auth.

| Directory                 | Holds                        |
| ------------------------- | ---------------------------- |
| `~/.local/share/skyforge` | auth, logs, bundled binaries |
| `~/.config/skyforge`      | `skyforge.jsonc`             |
| `~/.cache/skyforge`       | cache                        |
| `~/.local/state/skyforge` | state                        |
| `~/.skyforge`             | metrics log                  |

These paths are the same on every platform, Windows included — SkyForge resolves them from your home directory rather than from `%LOCALAPPDATA%` or `%APPDATA%`.

### macOS / Linux

```bash
for dir in ~/.local/share/skyforge ~/.config/skyforge ~/.cache/skyforge ~/.local/state/skyforge ~/.skyforge; do
  mkdir -p "$dir" 2>/dev/null
  if [ ! -d "$dir" ]; then
    echo "❌ $dir — could not create (permission denied)"
  elif [ -r "$dir" ] && [ -w "$dir" ]; then
    echo "✅ $dir — OK"
  else
    echo "❌ $dir — exists but no read/write access (run: sudo chown -R \$(whoami) $dir)"
  fi
done
```

If any directory shows ❌, fix ownership:

```bash
sudo chown -R $(whoami) ~/.local/share/skyforge
sudo chown -R $(whoami) ~/.config/skyforge
sudo chown -R $(whoami) ~/.cache/skyforge
sudo chown -R $(whoami) ~/.local/state/skyforge
sudo chown -R $(whoami) ~/.skyforge
```

> ⚠️ **Never run `skyforge` with `sudo`.** Running as root creates files owned by root — your normal user loses access and analytics stop working.

***

### Windows (PowerShell)

```powershell
$dirs = @(
  "$env:USERPROFILE\.local\share\skyforge",
  "$env:USERPROFILE\.config\skyforge",
  "$env:USERPROFILE\.cache\skyforge",
  "$env:USERPROFILE\.local\state\skyforge",
  "$env:USERPROFILE\.skyforge"
)
foreach ($dir in $dirs) {
  if (-not (Test-Path $dir)) {
    try { New-Item -ItemType Directory -Path $dir -Force | Out-Null }
    catch { Write-Host "❌ $dir — could not create (permission denied)"; continue }
  }
  try {
    $testFile = Join-Path $dir ".write_test"
    [IO.File]::WriteAllText($testFile, "test")
    Remove-Item $testFile
    Write-Host "✅ $dir — OK"
  } catch {
    Write-Host "❌ $dir — no write access (run as Administrator: icacls `"$dir`" /grant `"${env:USERNAME}:(OI)(CI)F`" /T)"
  }
}
```

If any directory shows ❌, run PowerShell as Administrator and fix:

```powershell
$username = $env:USERNAME
$dirs = @(
  "$env:USERPROFILE\.local\share\skyforge",
  "$env:USERPROFILE\.config\skyforge",
  "$env:USERPROFILE\.cache\skyforge",
  "$env:USERPROFILE\.local\state\skyforge",
  "$env:USERPROFILE\.skyforge"
)
foreach ($dir in $dirs) {
  if (Test-Path $dir) {
    icacls $dir /grant "${username}:(OI)(CI)F" /T
  }
}
```

> ⚠️ **Never run `skyforge` from a directory you don't own** (e.g. `C:\`). Always run from your home directory: `cd $env:USERPROFILE && skyforge`

***