> 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/getting-started.md).

# Getting Started

AI-powered ServiceNow development agent. Describe what you want — SkyForge builds it.

***

## 1 — Prerequisites

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

***

## 2 — Install SkyForge

```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 3.9.0
```

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

***

## 3 — 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.

### macOS / Linux

```bash
for dir in ~/.local/share/skyforge ~/.skyforge ~/.config/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) ~/.skyforge
sudo chown -R $(whoami) ~/.config/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:LOCALAPPDATA\skyforge",
  "$env:USERPROFILE\.skyforge",
  "$env:USERPROFILE\.config\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:LOCALAPPDATA\skyforge",
  "$env:USERPROFILE\.skyforge",
  "$env:USERPROFILE\.config\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`

***

## 4 — Run SkyForge

```bash
skyforge
```

Opens the web UI at `http://127.0.0.1:4096` in your browser.

![SkyForge home screen](/files/faMkJdlEAiH347q9MlIG)

### Other run modes

```bash
skyforge tui                    # terminal interface
skyforge serve                  # headless server (no browser)
skyforge run "find 5 incidents" # run a single prompt and exit
```

### Custom ports

```bash
skyforge --port 8080                     # custom web UI port
skyforge --port 8080 --mcp-port 9000     # custom both ports
skyforge --hostname 0.0.0.0              # listen on all interfaces (LAN access)
```

***

## 5 — Connect to ServiceNow

Open the **Hub** (top right) → **Instance tab** → **+ Add Instance**.

![Click Hub in the top right header](/files/mOcBbIaKLznmOsAvtnTm)

![Hub Instance tab — click + Add Instance](/files/d9BaJGuqShzlbBSnHVfn)

Choose your authentication method:

### Basic Auth *(developer instances only)*

Enter your instance URL, username, and password → **Connect**.

![Select Basic Auth](/files/tg95OQKIf63j0QBa0PO5)

![Basic Auth form filled in](/files/qlM2VFnS3N4obFUE1qTP)

> ⚠️ Never use Basic Auth in production.

> ⚠️ **Australia release and later:** ServiceNow requires the `snc_basic_auth_api_access` role for any account using Basic Auth against the REST API. Without it, all API calls return **401 Unauthorized** even with correct credentials.
>
> To assign the role:
>
> 1. Go to **User Administration → Users** → open the service account
> 2. Scroll to the **Roles** related list → **Edit**
> 3. Add `snc_basic_auth_api_access` → **Save**
>
> This applies to all ServiceNow instances on the **Australia release or newer**.

***

### OAuth 2.0 *(recommended for production)*

**First, set up an OAuth app in ServiceNow:**

1. Go to **System OAuth → Application Registry**
2. Click **New → Create an OAuth API endpoint for external clients**
3. Fill in:

| Field                      | Value                            | Why                                          |
| -------------------------- | -------------------------------- | -------------------------------------------- |
| **Name**                   | `SkyForge`                       | Cosmetic                                     |
| **Redirect URL**           | `http://localhost:3005/callback` | Must match exactly — no trailing slash       |
| **Active**                 | ✅ checked                        | Inactive apps silently reject requests       |
| **Accessible from**        | `All application scopes`         | Required for global scope                    |
| **Scope Restriction**      | `Broadly scoped`                 | **Critical** — `Securely scoped` returns 403 |
| **Access Token Lifespan**  | `1800` or `18000`                | Either works                                 |
| **Refresh Token Lifespan** | `8640000`                        | **Critical** — `0` breaks refresh            |

4. Submit → open the record → copy **Client ID** and **Client Secret**

**Then in SkyForge:**

Hub → Instance → + Add Instance → OAuth 2.0 → enter details → **Connect** → browser opens → click **Allow**.

***

### Browser Session / SSO *(for SSO/SAML instances)*

Use this when your instance requires SSO (Okta, Azure AD, SAML) and you have no local password.

1. Open your ServiceNow instance in Chrome/Firefox
2. Open **DevTools → Network tab** (F12)
3. Filter by `api/now` → right-click any `/api/now/table/` request → **Copy → Copy as cURL**

![Chrome DevTools — right-click a request → Copy → Copy as cURL](/files/ClEvyyhhtjmevHi2gsRq)

4. Hub → Instance → + Add Instance → Browser Session → paste cURL → **Connect**

> Session lasts \~8 hours. Re-paste a fresh cURL when expired.

> SkyForge replays the User-Agent captured in your cURL alongside the cookies — some corporate proxies/WAFs (Zscaler, Akamai, F5, etc.) reject requests where the User-Agent doesn't match what established the session, so this matters even if the cookies themselves are valid. If your instance still refuses the pasted session, that's usually IP-binding on the instance/network side (the session tied to the network it was captured on) rather than anything SkyForge can work around — running SkyForge from that same network, or switching to OAuth 2.0 (works from anywhere, no network dependency), are the two ways around it.

***

## 6 — Connect an AI Provider

Config file locations:

| Platform                    | Location                                              |
| --------------------------- | ----------------------------------------------------- |
| macOS / Linux (global)      | `~/.config/skyforge/skyforge.jsonc`                   |
| macOS / Linux (per-project) | `./skyforge.jsonc`                                    |
| Windows (global)            | `C:\Users\<username>\.config\skyforge\skyforge.jsonc` |
| Windows (per-project)       | `.\skyforge.jsonc`                                    |

### Anthropic (Claude) — recommended

```jsonc
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "anthropic": {
      "apiKey": "sk-ant-..."
    }
  },
  "model": "anthropic/claude-sonnet-4-6"
}
```

### OpenAI

```jsonc
{
  "provider": {
    "openai": {
      "apiKey": "sk-..."
    }
  },
  "model": "openai/gpt-4o"
}
```

### Custom / OpenAI-compatible *(LiteLLM, Ollama, company gateway)*

In the web UI: **Settings → Connect provider → Other → Custom**

Fill in: Provider ID, Base URL, Model ID, API key. Config is written automatically.

For LiteLLM proxy, edit `skyforge.jsonc` after connecting:

```jsonc
{
  "provider": {
    "litellm": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "LiteLLM Gateway",
      "options": {
        "baseURL": "https://your-litellm-gateway.com/v1",
        "apiKey": "sk-your-key",
        "litellmProxy": true
      },
      "models": {
        "your-model-name": {
          "name": "Your Model",
          "attachment": true,
          "reasoning": true,
          "modalities": {
            "input": ["text", "image"],
            "output": ["text"]
          }
        }
      }
    }
  }
}
```

> **`litellmProxy: true`** is required for LiteLLM — fixes tool call formatting.

After connecting, switch models with **Ctrl+P** → model picker.

***

## You're ready 🎉

Once connected, start a new session and try:

```
Find me 3 active incidents
```

See [Example Prompts](/docs/examples.md) for 30+ ready-to-use prompts across incidents, flows, catalog, ATF, Service Portal, and more.

***

## Troubleshooting

**"Authentication failed" / 401 errors**

* Refresh Token Lifespan must not be `0` — set to `8640000`
* Scope Restriction must be `Broadly scoped` not `Securely scoped`
* Redirect URL must be exactly `http://localhost:3005/callback`

**SSO session expired**

Copy a fresh cURL from DevTools and re-authenticate via Hub → Instance tab.

**MCP not connecting**

```bash
tail -f ~/.skyforge/skyforge-mcp.log
```

**Reset everything**

**macOS / Linux:**

```bash
rm -rf ~/.config/skyforge ~/.local/share/skyforge ~/.local/share/opentui ~/.cache/skyforge ~/.skyforge
npm i -g @skyforgeai/skyforge@latest && skyforge
```

**Windows (PowerShell):**

```powershell
Remove-Item -Recurse -Force "$env:USERPROFILE\.config\skyforge"
Remove-Item -Recurse -Force "$env:USERPROFILE\.local\share\skyforge"
Remove-Item -Recurse -Force "$env:USERPROFILE\.cache\skyforge"
Remove-Item -Recurse -Force "$env:USERPROFILE\.skyforge"
npm i -g @skyforgeai/skyforge@latest; skyforge
```

***

## Advanced configuration

See [Configuration](/docs/configuration.md) for: keyboard shortcuts, agents, MCP servers, permissions, logs, environment variables, and full config reference.

**Want to use SkyForge inside Claude Desktop or Claude Code instead of the SkyForge app?** Run `skyforge mcp serve` and upload the orchestrator skill — see [Custom Skills → Using SkyForge in Claude Desktop / Claude Code](/docs/custom-skills.md#using-skyforge-in-claude-desktop--claude-code).

***

## Need help?

[Submit an issue →](https://github.com/tryskyforge/skyforgeissues)