Skip to content

Quick Start

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

Install

bash
npm install -g cloudservice
cloudservice

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

bash
npx cloudservice@latest

Authenticate

Paste your CloudService API key when prompted. The installer detects whether the key is OpenAI-compatible only, Claude-compatible only, or both, then hides incompatible client setup choices.

text
Enter your CloudService API key:

Use the web guided setup

If you prefer a browser checklist, open the CloudService guided setup wizard. 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 cloudservice setup in a terminal when you want automatic local configuration.

That sign-in is shared across yourdomain.example, docs.yourdomain.example, dashboard.yourdomain.example, web.yourdomain.example, and studio.yourdomain.example. 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 one billing path

Your choice is remembered across the documentation. Then select the card that matches your client protocol.

For a key funded with a dollar credit balance.

OpenAI-compatible Chat Completions or Responses

Use with: Codex, OpenCode, Cursor, Roo Code, SDKs, and direct HTTP

Base URL to enter

https://api.yourdomain.example/v1

Native Anthropic Messages

Use with: Claude Code, Claude Desktop, and native Messages clients

Base URL to enter

https://api.yourdomain.example

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; it does not read Claude Code's configuration.

If a key already exists, CloudService shows it masked and asks what to do:

text
✓ Existing CloudService 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; it does not read Claude Code settings.

Verify Installation

bash
cloudservice doctor

cloudservice doctor verifies your API key, live model endpoint, streaming path, usage path, and local client configuration files.

bash
cloudservice models

cloudservice 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 CloudService directly in the browser without configuring a local SDK.

  • Web Chat — workspace-scoped browser conversations.
  • Studio — prompt-to-website and prompt-to-app generation with previews.

First Chat Example

Select a model from cloudservice 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.

bash
export CLOUDSERVICE_API_KEY="ak_live_..."
# API-credit key:
export CLOUDSERVICE_BASE_URL="https://api.yourdomain.example/v1"
# API-token key used with an OpenAI-compatible client:
# export CLOUDSERVICE_BASE_URL="https://api.yourdomain.example/token/v1"

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

OpenAI SDK Example

client.mjs
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.CLOUDSERVICE_API_KEY,
  baseURL: process.env.CLOUDSERVICE_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