# Configuration

***

## Config File

`skyforge.jsonc` is picked up automatically when you run `skyforge`. SkyForge searches in this order:

| Location                                              | When to use                                     |
| ----------------------------------------------------- | ----------------------------------------------- |
| `./skyforge.jsonc`                                    | Current directory — per-project (all platforms) |
| `~/skyforge.jsonc`                                    | Home directory — personal global (macOS/Linux)  |
| `~/.config/skyforge/skyforge.jsonc`                   | XDG config dir — global (macOS/Linux)           |
| `C:\Users\<username>\.config\skyforge\skyforge.jsonc` | Global config (Windows)                         |

**Tip:** Start with `~/skyforge.jsonc` so it works from any directory, then override per-project as needed.

***

## AI Providers

### Anthropic (Claude)

```jsonc
{
  "provider": {
    "anthropic": {
      "apiKey": "sk-ant-..."
    }
  },
  "model": "anthropic/claude-sonnet-4-6"
}
```

Models: `claude-opus-4-6`, `claude-sonnet-4-6`, `claude-haiku-4-5`

### OpenAI

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

### Google Gemini

```jsonc
{
  "provider": {
    "google": {
      "apiKey": "AIza..."
    }
  },
  "model": "google/gemini-2.5-pro"
}
```

### Azure OpenAI

```jsonc
{
  "provider": {
    "azure": {
      "apiKey": "your-azure-key",
      "resourceName": "your-resource-name"
    }
  },
  "model": "azure/gpt-4o"
}
```

### AWS Bedrock

```jsonc
{
  "provider": {
    "amazon-bedrock": {
      "region": "us-east-1"
    }
  }
}
```

Uses your local AWS credentials (`~/.aws/credentials` on macOS/Linux, `C:\Users\<username>\.aws\credentials` on Windows).

### Groq

```jsonc
{
  "provider": {
    "groq": {
      "apiKey": "gsk_..."
    }
  }
}
```

### OpenRouter

```jsonc
{
  "provider": {
    "openrouter": {
      "apiKey": "sk-or-..."
    }
  }
}
```

### Custom / OpenAI-Compatible Provider

Any OpenAI-compatible endpoint works — self-hosted vLLM, LiteLLM, Ollama, or a hosted gateway.

**TUI:** `Ctrl+P → Connect a provider → Custom (OpenAI-compatible)`

Walks you through: Provider ID → Display name → Base URL → Model ID → Model name → API key. Config is written to `~/.config/skyforge/skyforge.jsonc` automatically.

**Web UI:** Settings icon → **Connect provider** → scroll to **Other** → **Custom**

For advanced options, edit `~/.config/skyforge/skyforge.jsonc` after setup:

**LiteLLM / vLLM gateway:**

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

> **`litellmProxy: true`** is required for LiteLLM/vLLM — fixes tool call formatting and enables image passthrough.

**Hosted gateway (company API):**

```jsonc
{
  "provider": {
    "mygateway": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "My Gateway",
      "options": {
        "baseURL": "https://your-gateway.example.com/v1",
        "apiKey": "sk-..."
      },
      "models": {
        "your-model-name": {
          "name": "My Model"
        }
      }
    }
  }
}
```

**Ollama (local):**

```jsonc
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama",
      "options": {
        "baseURL": "http://localhost:11434/v1"
      },
      "models": {
        "llama3.2": {
          "name": "Llama 3.2"
        }
      }
    }
  }
}
```

### Multiple Providers

```jsonc
{
  "provider": {
    "anthropic": { "apiKey": "sk-ant-..." },
    "openai": { "apiKey": "sk-..." }
  },
  "model": "anthropic/claude-sonnet-4-6"
}
```

Switch models mid-session with **Ctrl+P** → `model`.

***

## ServiceNow Connection

SkyForge supports three authentication methods. All are configured via the TUI (`Ctrl+P → ServiceNow Auth`) or Web UI (Settings icon → ServiceNow Auth) — no manual config file editing required.

### OAuth 2.0 (Recommended)

Best for production instances. Requires setting up an OAuth app in ServiceNow first.

#### Setting up OAuth in ServiceNow

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

   | Field                      | Value                            | Why                                                           |
   | -------------------------- | -------------------------------- | ------------------------------------------------------------- |
   | **Name**                   | `SkyForge`                       | Cosmetic                                                      |
   | **Redirect URL**           | `http://localhost:3005/callback` | Must match byte-for-byte. No trailing slash.                  |
   | **Active**                 | ✅ checked                        | Inactive apps silently reject every request                   |
   | **Accessible from**        | `All application scopes`         | Required for global scope                                     |
   | **Scope Restriction**      | `Broadly scoped`                 | **Critical.** `Securely scoped` blocks all `/api/now/*` calls |
   | **Access Token Lifespan**  | `1800` or `18000`                | Either works                                                  |
   | **Refresh Token Lifespan** | `8640000` (100 days)             | **Critical.** If `0`, every refresh token is dead on arrival  |
4. Submit, open the record, reveal and copy **Client ID** and **Client Secret**

#### Authenticate

**TUI:** `Ctrl+P → ServiceNow Auth → OAuth`

**Web UI:** Settings icon → ServiceNow Auth → OAuth 2.0

A browser opens to the consent page — click **Allow**.

***

### Basic Auth (Development only)

**TUI:** `Ctrl+P → ServiceNow Auth → Basic Auth`

**Web UI:** Settings icon → ServiceNow Auth → Basic Auth

> ⚠️ Basic auth is for development only. Use OAuth for production.

***

### Browser Session / SSO

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

**TUI:** `Ctrl+P → ServiceNow Auth → Browser Session (SSO)`

1. Enter instance URL → Enter (browser opens)
2. DevTools → Network → filter `api/now` → right-click any request → Copy as cURL
3. Paste into textarea → **Ctrl+S**

**Web UI:** Settings icon → ServiceNow Auth → Browser Session (SSO)

1. Follow the on-screen instructions
2. Paste cURL → **Connect**

> Sessions last \~8 hours. Re-paste a fresh cURL when expired.\
> Restart SkyForge after connecting to activate MCP tools.

### Multiple Instances

```jsonc
{
  "mcp": {
    "servicenow-dev": {
      "type": "local",
      "command": ["skyforge", "mcp", "start"],
      "environment": {
        "SERVICENOW_INSTANCE_URL": "https://dev12345.service-now.com",
        "SERVICENOW_CLIENT_ID": "dev-client-id",
        "SERVICENOW_CLIENT_SECRET": "dev-secret"
      }
    },
    "servicenow-prod": {
      "type": "local",
      "command": ["skyforge", "mcp", "start"],
      "environment": {
        "SERVICENOW_INSTANCE_URL": "https://prod.service-now.com",
        "SERVICENOW_CLIENT_ID": "prod-client-id",
        "SERVICENOW_CLIENT_SECRET": "prod-secret"
      }
    }
  }
}
```

***

## External MCP Servers

SkyForge supports any MCP-compatible server:

### Remote MCP (SSE/HTTP)

```jsonc
{
  "mcp": {
    "context7": {
      "type": "remote",
      "url": "https://mcp.context7.com/mcp"
    }
  }
}
```

### Local MCP (stdio)

```jsonc
{
  "mcp": {
    "my-custom-server": {
      "type": "local",
      "command": ["node", "./my-mcp-server.js"],
      "environment": {
        "API_KEY": "..."
      }
    }
  }
}
```

***

## Permissions

Control what SkyForge can do:

```jsonc
{
  "permission": {
    "bash": "ask",           // ask before running shell commands
    "write": "allow",        // allow file writes
    "read": "allow",         // allow file reads
    "external_directory": "deny"  // deny access outside project
  }
}
```

Options: `"allow"`, `"ask"`, `"deny"`

***

## Custom Agents

Define your own agents:

```jsonc
{
  "agent": {
    "servicenow-readonly": {
      "model": "anthropic/claude-haiku-4-5",
      "description": "Read-only ServiceNow queries",
      "permission": {
        "bash": "deny",
        "write": "deny"
      },
      "system": "You are a ServiceNow read-only assistant. Only query data, never create or modify anything."
    }
  }
}
```

***

## Disabling/Enabling Tools

```jsonc
{
  "tools": {
    "Bash": false,        // disable bash tool
    "WebSearch": false    // disable web search
  }
}
```

***

## Ports & Server

By default SkyForge runs on:

* **Main server** (web UI + API): `:4096`
* **HTTP MCP server** (VS Code / Claude.ai): `:3006`

### Custom ports via CLI flags

```bash
skyforge --port 8080                    # custom main server port
skyforge --mcp-port 9000                # custom HTTP MCP port
skyforge --port 8080 --mcp-port 9000    # both at once

skyforge serve --port 8080 --mcp-port 9000
```

### Custom ports via environment variables

```bash
OPENCODE_SERVER_PORT=8080 SN_MCP_HTTP_PORT=9000 skyforge
```

### Custom hostname

```bash
skyforge --hostname 0.0.0.0   # listen on all interfaces (LAN access)
```

> When running on a custom MCP port, update your VS Code / Claude settings:
>
> ```json
> { "type": "http", "url": "http://localhost:9000/mcp" }
> ```

***

## Environment Variables

Instead of `skyforge.jsonc`, you can use environment variables:

```bash
export ANTHROPIC_API_KEY="sk-ant-..."
export OPENAI_API_KEY="sk-..."
export SERVICENOW_INSTANCE_URL="https://dev12345.service-now.com"
export SERVICENOW_CLIENT_ID="abc123"
export SERVICENOW_CLIENT_SECRET="secret"

skyforge
```

***

## Full Config Reference

```jsonc
{
  // AI provider configurations
  "provider": {
    "anthropic": { "apiKey": "..." },
    "openai": { "apiKey": "..." }
  },

  // Default model (provider/model format)
  "model": "anthropic/claude-sonnet-4-6",

  // Small model for lightweight tasks (title generation etc.)
  "model.mini": "anthropic/claude-haiku-4-5",

  // MCP server configurations
  "mcp": {
    "servicenow": { ... }
  },

  // Tool enable/disable
  "tools": {
    "Bash": true,
    "WebSearch": true
  },

  // Permissions
  "permission": {
    "bash": "ask",
    "write": "allow",
    "read": "allow"
  },

  // Disable specific providers
  "disabled_providers": ["openrouter"],

  // Only enable specific providers
  "enabled_providers": ["anthropic", "openai"],

  // Custom agents
  "agent": { ... },

  // Plugins (npm packages)
  "plugin": ["my-skyforge-plugin"]
}
```

***

## Support

Have a bug or feature request? Submit it at [**GitHub Issues**](https://github.com/tryskyforge/skyforgeissues).

## License

SkyForge is licensed under the [Elastic License 2.0](/docs/license.md). Free for personal and internal use. Commercial redistribution requires a license.

***

## Running SkyForge

### Web interface (default)

```bash
skyforge
# or explicitly:
skyforge web
```

Opens `http://127.0.0.1:4096` in your browser.

### TUI (terminal interface)

```bash
skyforge tui
```

### Headless server (API only)

```bash
skyforge serve
skyforge serve --port 8080 --mcp-port 9000
```

### Run with a prompt directly

```bash
skyforge run "query the last 5 critical incidents"
```

### Attach TUI to a running server

```bash
skyforge attach http://host:4096
```

***

## Logs

| Log                 | macOS / Linux                         | Windows                                           |
| ------------------- | ------------------------------------- | ------------------------------------------------- |
| Session (dev build) | `~/.local/share/skyforge/log/dev.log` | `%USERPROFILE%\.local\share\skyforge\log\dev.log` |
| Session (installed) | `~/.local/share/skyforge/log/*.log`   | `%USERPROFILE%\.local\share\skyforge\log\`        |
| MCP calls           | `~/.skyforge/skyforge-mcp.log`        | `%USERPROFILE%\.skyforge\skyforge-mcp.log`        |
| MCP metrics         | `~/.skyforge/skyforge-metrics.log`    | `%USERPROFILE%\.skyforge\skyforge-metrics.log`    |

```bash
# Tail active log (dev build)
tail -f ~/.local/share/skyforge/log/dev.log

# Tail latest session log (installed binary)
ls -t ~/.local/share/skyforge/log/*.log | head -1 | xargs tail -f

# Watch MCP tool calls
tail -f ~/.skyforge/skyforge-mcp.log

# Full debug output
skyforge --log-level DEBUG --print-logs
```

***

## Keyboard Shortcuts (TUI)

SkyForge uses a **leader key** pattern — press and **release** `Ctrl+X` first, then press the second key.

| Key               | Action                             |
| ----------------- | ---------------------------------- |
| `Ctrl+X` then `A` | Open agent picker                  |
| `Shift+Tab`       | Cycle to next agent                |
| `Ctrl+Shift+Tab`  | Cycle to previous agent            |
| `Escape`          | Interrupt / stop current operation |
| `Ctrl+X` then `↑` | Go to parent session               |
| `Ctrl+X` then `→` | Next child session                 |
| `Ctrl+X` then `←` | Previous child session             |
| `Ctrl+P`          | Command palette                    |
| `/connect`        | Add AI provider                    |
| `/models`         | Switch model                       |
| `/themes`         | Change theme                       |
| `Ctrl+Shift+A`    | Toggle auto-accept permissions     |
| `Ctrl+C`          | Exit SkyForge                      |

***

## Agents

| Agent       | Trigger     | Description                                                 |
| ----------- | ----------- | ----------------------------------------------------------- |
| **Build**   | Default     | Full tool access — creates and deploys ServiceNow artifacts |
| **Plan**    | `Shift+Tab` | Read-only — analysis and exploration                        |
| **Review**  | `Shift+Tab` | Code review — writes report to `.skyforge/reviews/`         |
| **General** | `@general`  | Multi-step subagent for complex parallel tasks              |

Switch between Build / Plan / Review with `Shift+Tab`. Invoke General with `@general`.

Custom agents can be defined in `skyforge.jsonc` — see [Custom Agents](#custom-agents) above.

***

## Troubleshooting

### Reset to clean state

**macOS / Linux:**

```bash
rm -rf ~/.config/skyforge
rm -rf ~/.local/share/skyforge
rm -rf ~/.local/share/opentui
rm -rf ~/.cache/skyforge
rm -rf ~/.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"
```

Then reinstall:

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

### OAuth errors

| Error                                         | Fix                                                                 |
| --------------------------------------------- | ------------------------------------------------------------------- |
| `OAuth refresh token flow failed: 401`        | Refresh Token Lifespan is `0` — set to `8640000`, re-auth           |
| `Access to unscoped api is not allowed` (403) | Scope Restriction is `Securely scoped` — change to `Broadly scoped` |
| `Invalid redirect_uri`                        | Redirect URL must be exactly `http://localhost:3005/callback`       |

### SSO / Browser Session errors

| Error                                    | Fix                                                         |
| ---------------------------------------- | ----------------------------------------------------------- |
| `Session verification failed: HTTP 401`  | Session expired — copy fresh cURL from DevTools and re-auth |
| `No cookies in cURL`                     | Wrong request — filter DevTools by `api/now/table/`         |
| MCP tools not available after connecting | Restart SkyForge                                            |

### Other

| Problem                        | Fix                                                                    |
| ------------------------------ | ---------------------------------------------------------------------- |
| `Tool not found`               | Tools are lazy-loaded — type `search for X tools` first                |
| MCP not connecting             | `tail -f ~/.skyforge/skyforge-mcp.log` or `SN_MCP_DEBUG=true skyforge` |
| Web UI file attach not working | Must be on `localhost` or HTTPS                                        |


---

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