# ScaleMax Documentation

> Start with Web Chat and Studio, or connect your own tools through the OpenAI-compatible and Anthropic Messages APIs.

Use ScaleMax in the browser with Web Chat and Studio, or connect your own tools through the OpenAI-compatible API and Anthropic Messages gateway.

## Choose your path

- [Web Chat](https://docs.scalemax.pro/docs/web-chat) — browser conversations for everyday AI work.
- [Studio](https://docs.scalemax.pro/docs/studio) — generate websites and simple apps with rendered previews.
- [API and client setup](https://docs.scalemax.pro/docs/quick-start) — connect SDKs and supported clients.

## Install

Requires Node.js `18.19` or later with `npm` and `npx`.

**macOS / Linux**

```bash
npm install -g scalemax
scalemax
```

**Windows PowerShell**

```powershell
npm.cmd install -g scalemax
scalemax.cmd
```

Windows PowerShell blocks npm’s .ps1 launchers by default (“running scripts is disabled on this system”), so these commands use the .cmd launcher: npx.cmd, npm.cmd, scalemax.cmd. In Command Prompt you can leave out .cmd.

Or run the latest CLI once:

**macOS / Linux**

```bash
npx scalemax@latest
```

**Windows PowerShell**

```powershell
npx.cmd scalemax@latest
```

Windows PowerShell blocks npm’s .ps1 launchers by default (“running scripts is disabled on this system”), so these commands use the .cmd launcher: npx.cmd, npm.cmd, scalemax.cmd. In Command Prompt you can leave out .cmd.

## Get an API key

New to ScaleMax? [Choose API credit or a provider-scoped token pack (Claude, OpenAI, Gemini, Grok, Qwen, Local Models, or an exact-model pack such as DeepSeek V4 Flash) and get your API key](https://dashboard.scalemax.pro/pricing). No subscription is required. A token key is provider-scoped: Claude tokens are for Claude models, OpenAI tokens are for OpenAI-compatible models, and each of Gemini, Grok, Qwen, and Local Models tokens are for that family's models only. MiMo models are included in the Local Models pack.

## Authenticate

Paste your ScaleMax API key when prompted.

```text
Enter your ScaleMax API key:
```

## Set the matching gateway URL

The CLI makes this choice for you. For manual SDK or client setup, use the billing surface and protocol that match the key and client.

**Start with the key you bought.** Choose its billing path, then the row that matches your client's protocol.

| Key type | Protocol | Use with | Base URL |
| --- | --- | --- | --- |
| API Credit | OpenAI-compatible Chat Completions or Responses | Codex, OpenCode, Cursor, Roo Code, SDKs, and direct HTTP | `https://api.scalemax.pro/v1` |
| API Credit | Native Anthropic Messages | Claude Code, Claude Desktop, and native Messages clients | `https://api.scalemax.pro` |
| Token Budget | OpenAI, Gemini, Grok, Qwen, DeepSeek, or Local Models token pack · OpenAI-compatible API | Codex, OpenCode, Cursor, Roo Code, SDKs, and direct HTTP | `https://api.scalemax.pro/token/v1` |
| Token Budget | Claude token pack · Native Anthropic Messages | Claude Code, Claude Desktop, and native Messages clients | `https://api.scalemax.pro/token` |
| Token Budget | Claude token pack · OpenAI-compatible adapter | OpenCode, Cursor, Roo Code, compatible SDKs, and direct HTTP | `https://api.scalemax.pro/token/v1` |

**The protocol decides whether the client field ends in `/v1`.** OpenAI-compatible clients use a base URL ending in `/v1`. Native Anthropic clients use the origin only, without `/v1`, because they append `/v1/messages` themselves. A Claude token key therefore reaches `/token/v1/messages` when the native client builds its request.

Use the key's matching billing surface and only models returned by its authenticated catalog. A Claude token key and an OpenAI token key are provider-scoped; neither can be swapped onto the other's models.

Claude Desktop is a native Anthropic client with its own third-party inference settings. Follow the [Claude Desktop guide](https://docs.scalemax.pro/docs/manual-configuration/claude-desktop); it does not read Claude Code's configuration.

If already configured, the installer shows the stored key safely masked:

```text
✓ Existing ScaleMax configuration detected.

API key:
••••••••••••••••abcd

1. Keep existing key
2. Replace with a new key
3. Remove configuration
4. Exit
```

## Configure clients

The installer detects and configures supported clients automatically:

- Codex
- Cursor
- Roo Code
- Cline
- Continue
- TRAE SOLO
- Claude Code
- OpenCode
- OpenClaw
- Hermes
- Cherry Studio
- API Code

Managed Claude Desktop on 3P uses a separate [third-party inference guide](https://docs.scalemax.pro/docs/manual-configuration/claude-desktop) and does not inherit Claude Code settings. The full list, including clients the installer cannot configure, is in [Supported clients](https://docs.scalemax.pro/docs/supported-clients).

## Verify installation

**macOS / Linux**

```bash
scalemax doctor
scalemax models
```

**Windows PowerShell**

```powershell
scalemax.cmd doctor
scalemax.cmd models
```

`scalemax doctor` checks your key, model endpoint, streaming, usage path, and client configuration files. Its streaming check sends a small billable request, and a configured client verifier may send an additional small billable request.

`scalemax models` fetches the live model list from the matching authenticated catalog: `/v1/models` for API credit or `/token/v1/models` for API tokens.

## First chat example

For an OpenAI-compatible client, select the base URL for the key first. Use only an ID returned by that key's authenticated model catalog.

**macOS / Linux**

```bash
export SCALEMAX_API_KEY="sm_live_..."
# API-credit key:
export SCALEMAX_BASE_URL="https://api.scalemax.pro/v1"
# API-token key used through an OpenAI-compatible client:
# export SCALEMAX_BASE_URL="https://api.scalemax.pro/token/v1"

curl "$SCALEMAX_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $SCALEMAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_AUTHENTICATED_MODEL_ID",
    "max_tokens": 16,
    "messages": [{"role": "user", "content": "Reply with exactly OK"}]
  }'
```

**Windows PowerShell**

```powershell
$env:SCALEMAX_API_KEY = "sm_live_..."
# API-credit key:
$env:SCALEMAX_BASE_URL = "https://api.scalemax.pro/v1"
# API-token key used through an OpenAI-compatible client:
# $env:SCALEMAX_BASE_URL = "https://api.scalemax.pro/token/v1"

@'
{
  "model": "YOUR_AUTHENTICATED_MODEL_ID",
  "max_tokens": 16,
  "messages": [{"role": "user", "content": "Reply with exactly OK"}]
}
'@ | Set-Content -Path body.json

curl.exe "$env:SCALEMAX_BASE_URL/chat/completions" `
  -H "Authorization: Bearer $env:SCALEMAX_API_KEY" `
  -H "Content-Type: application/json" `
  --data-binary "@body.json"
```

PowerShell changes quotes inside a JSON argument, so the request body goes into body.json first and curl.exe sends that file. Type curl.exe, not curl: in Windows PowerShell 5.1, curl is a different command.

## Base URL

OpenAI-compatible SDKs use `https://api.scalemax.pro/v1` for API credit or `https://api.scalemax.pro/token/v1` for API tokens. Native Claude apps use the origin-only entries in the table above instead.

## Next steps

- [Get an API key / buy API credit or tokens](https://dashboard.scalemax.pro/pricing)
- [Open Web Chat guide](https://docs.scalemax.pro/docs/web-chat)
- [Open Studio guide](https://docs.scalemax.pro/docs/studio)
- [Detailed Quick Start](https://docs.scalemax.pro/docs/quick-start)
- [Supported models](https://docs.scalemax.pro/docs/models)
- [API compatibility](https://docs.scalemax.pro/docs/openai-compatibility)
- [Billing, API credits and token packs](https://docs.scalemax.pro/docs/billing)
- [Troubleshooting](https://docs.scalemax.pro/docs/troubleshooting)
- [What changed recently](https://docs.scalemax.pro/docs/changelog)