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

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

***

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

***

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

***

## Need help?

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://skyforgeai.gitbook.io/docs/getting-started.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.