# Quick Start

> Install the ScaleMax CLI, authenticate an API-credit or token key, choose the correct base URL, and verify your first API request.

Start with the CLI. It writes only ScaleMax-managed client configuration and always reads the live model list from the API.

## Step 0: Get a key

Everything below needs a ScaleMax API key (it starts with `sm_live_`). [Start a free trial](https://web.scalemax.pro/trial) with no card, or [buy API credit or a token pack from ₹250](https://dashboard.scalemax.pro/pricing). The key is shown once, so copy it somewhere safe.

## Install

Requires Node.js `18.19` or later with `npm` and `npx`. Pick your system; the commands differ on Windows.

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

For a one-time run without keeping a global install:

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

## Authenticate

Paste your ScaleMax API key when prompted. The installer validates its primary scope and authenticated effective model catalog, then hides client setup choices that cannot use any model returned for that key.

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

## Use the web guided setup

If you prefer a browser checklist, open the [ScaleMax guided setup wizard](https://dashboard.scalemax.pro/setup). Sign in once with your key and it shows the matching credit or token URL, provider scope, live key-scoped models, and links to Web Chat, Studio, and client-specific instructions. The web wizard never reveals the key and cannot edit local files; use `scalemax setup` in a terminal when you want automatic local configuration.

That sign-in is shared across `scalemax.pro`, `docs.scalemax.pro`, `dashboard.scalemax.pro`, `web.scalemax.pro`, and `studio.scalemax.pro`. Switching surfaces does not change the active billing identity.

## Choose the manual base URL

The CLI detects this automatically. If you are configuring an SDK or client yourself, select the row that matches both the key you bought and that client's protocol.

**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 a key already exists, ScaleMax shows it masked and asks what to do:

```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 automatically detects these supported configuration targets and can configure one or all targets compatible with the key scope:

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

Claude Desktop on 3P uses a separate managed Gateway configuration. Follow the [Claude Desktop guide](https://docs.scalemax.pro/docs/manual-configuration/claude-desktop); it does not read Claude Code settings.

## Verify Installation

**macOS / Linux**

```bash
scalemax doctor
```

**Windows PowerShell**

```powershell
scalemax.cmd doctor
```

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

**macOS / Linux**

```bash
scalemax models
```

**Windows PowerShell**

```powershell
scalemax.cmd models
```

`scalemax models` fetches the current live model list from the matching authenticated endpoint: `/v1/models` for API credit or `/token/v1/models` for an API-token key. Unsupported or disabled models disappear immediately.

## Use browser apps

After your access is ready, you can use ScaleMax directly in the browser without configuring a local SDK.

- [Web Chat](https://docs.scalemax.pro/docs/web-chat) — workspace-scoped browser conversations.
- [Studio](https://docs.scalemax.pro/docs/studio) — prompt-to-website and prompt-to-app generation with previews.

## First Chat Example

Select a model from `scalemax models`, then send a standard OpenAI-compatible request. API-credit users set the first base URL; API-token users set the second. A Claude token key must use a Claude model returned by its 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 with 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 with 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.

## OpenAI SDK Example

client.mjs:

```javascript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.SCALEMAX_API_KEY,
  baseURL: process.env.SCALEMAX_BASE_URL,
});

const response = await client.chat.completions.create({
  model: "YOUR_AUTHENTICATED_MODEL_ID",
  messages: [{ role: "user", content: "Reply with exactly OK" }],
  max_tokens: 16,
});

console.log(response.choices[0].message.content);
```

## Next steps

- Copy a working request in [cURL](https://docs.scalemax.pro/docs/examples/curl), [Python](https://docs.scalemax.pro/docs/examples/python), or [JavaScript](https://docs.scalemax.pro/docs/examples/javascript).
- Read the full [ScaleMax API reference](https://docs.scalemax.pro/docs/api-reference) for every endpoint and parameter.
- Check [rate limits](https://docs.scalemax.pro/docs/rate-limits) and [error codes](https://docs.scalemax.pro/docs/error-codes) before going to production.