# Encrypted API client and CLI

Use Sideroom from a Node.js application or your terminal. The client verifies the gateway against a policy you approve, encrypts your messages, and authenticates the response. Requests use the mainnet app at [app.sideroom.sh](https://app.sideroom.sh/?connect=1) by default and spend the same USDG-funded account balance as chat.

The client is distributed as source in this repository and the [downloadable client kit](https://sideroom.sh/downloads/sideroom-client/sideroom-client.tar.gz), with TypeScript declarations in `client/sideroom.d.mts`. There is no published npm SDK to install. Use Node.js 22.22 or newer, including Node.js 24. From the repository root or extracted `sideroom-client` directory, install the locked dependencies:

```sh
npm ci --ignore-scripts
```

## Create a key and keep it private

In the app, open **Settings → API keys**. Under **Create an API key**, enter a **Key name** and select **Create key**. Use **Copy key** under **Your new key**; the full key is shown only once. Keys have inference scope only: they cannot manage keys or your profile, or read saved chats. To revoke one, select **Revoke → Revoke key** under **Your keys**.

Before your first call, fund the issuing account with USDG in **Wallet**. An API key has no separate balance; chat and API calls spend that account's shared usage credits.

Create a private environment file in the directory where you will run the examples:

```sh
umask 077
touch .env.api
chmod 600 .env.api
```

Open `.env.api` in an editor and replace the placeholder with the key you copied:

```dotenv
SIDEROOM_API_KEY=REPLACE_WITH_YOUR_ACCOUNT_API_KEY
# Uncomment only for a private preview that requires a password:
# SIDEROOM_PREVIEW_PASSWORD=REPLACE_WITH_PREVIEW_PASSWORD
```

The CLI accepts credentials through environment variables only. The JavaScript examples read the same variables. Keep keys out of source code, browser bundles, logs, CLI arguments and URLs. This repository ignores `.env.*` files except `.env.example`; do not put credentials in that example or force-add `.env.api` to Git. When moving the client to another project, preserve those exclusions. The optional preview password uses HTTP Basic authentication with the fixed username `sideroom`.

## Approve the gateway policy

Obtain `approved.json` through an independent release review before sending a prompt. The client kit includes a published release policy; review its measurements independently before using that file in place of `approved.json` below.

- For `mode: "aws-nitro"`, approve the specific release's PCR0, PCR1, and PCR2 values in `approvedPcrs`. The client checks fresh attestation and the binding to the gateway encryption key against that policy for every request.
- For development with `mode: "local-process"`, independently pin the gateway's encryption-key configuration hash in `keyConfigHash`. This authenticates the pinned process key; **it is not TEE verification**.

Do not approve values merely because the relay reports them, labels itself verified, or serves a policy file. Repository test fixtures are not an approved release policy. A changed gateway image needs newly reviewed measurements. Gateway verification does not independently verify upstream inference hardware or model weights.

## Call the API from JavaScript

Save this complete example as `example.mjs` beside the `client` directory. It reads your approved policy from disk and your API key from the environment, then prints only the completed answer:

```js
import { readFile } from 'node:fs/promises';
import { createSideroomClient, SideroomError } from './client/sideroom.mjs';

try {
  const policy = JSON.parse(await readFile('approved.json', 'utf8'));
  const client = createSideroomClient({
    apiKey: process.env.SIDEROOM_API_KEY,
    policy,
    url: 'https://app.sideroom.sh',
    previewPassword: process.env.SIDEROOM_PREVIEW_PASSWORD,
  });

  const result = await client.chat({
    model: 'phala/gemma-4-26b-a4b-uncensored',
    messages: [
      { role: 'user', content: 'Explain public-key encryption in three sentences.' },
    ],
  });

  console.log(result.reply);
  console.error(JSON.stringify({
    model: result.model,
    usage: result.usage,
    billing: result.billing,
    finishReason: result.finishReason,
    gatewayVerified: result.transport.gatewayVerified,
  }));
} catch (error) {
  if (error instanceof SideroomError) {
    console.error(JSON.stringify({
      code: error.code,
      status: error.status,
      billing: error.billing,
    }));
  } else {
    console.error('Unable to complete the request. Check the policy file and account.');
  }
  process.exitCode = 1;
}
```

Run it from that directory:

```sh
node --env-file=.env.api example.mjs
```

### Client interface

```js
const client = createSideroomClient({ apiKey, policy, url, previewPassword, fetchImpl });
const result = await client.chat({ messages, model }, { signal, onDelta });
```

`apiKey` and `policy` are required. `policy` is the parsed JSON object, not a filename. `url` defaults to `https://app.sideroom.sh`; `model` defaults to Gemma 4. `previewPassword`, `fetchImpl`, and the second argument to `chat` are optional. `fetchImpl` defaults to the runtime's `fetch`; an override is trusted application code and must preserve the request's security settings.

Use one HTTPS origin as `url`, without credentials, a path, a query or a fragment. Loopback HTTP is accepted for local development. The client uses fixed paths on that origin and rejects redirects. Each request has a 125-second client timeout; pass an `AbortSignal` to cancel sooner, for example `{ signal: AbortSignal.timeout(30_000) }`. Cancellation does not guarantee that inference stopped or that no credits were spent.

The resolved result contains:

| Field | Meaning |
| --- | --- |
| `reply` | The complete authenticated answer text. |
| `model` | The selected model ID string. |
| `usage` | `{ available, inputTokens, outputTokens }`. Read counts only when `available` is `true`; zero counts with `available: false` mean unknown usage. |
| `billing` | `{ chargedUnits, usageKnown }` when valid billing information is present; otherwise `undefined`. This is the account's retail charge or retained reservation. |
| `finishReason` | A recognized provider completion reason, or `null`. `length` means the response reached its output limit. |
| `transport` | Gateway connection evidence, including `mode`, `requestId`, `keyConfigHash`, `encrypted`, `responseAuthenticated`, `gatewayVerified`, `attestation`, and `checkedAt`. |

`transport.gatewayVerified` is `true` only for a successfully verified AWS Nitro gateway. A `local-process` result authenticates a pinned development key, and its `attestation` is `null`. Saved transport evidence describes that exchange; it is not fresh verification of a later connection.

### Stream an answer

Pass `onDelta` as a request option to receive text as it arrives. This example uses the `client` configured above:

```js
let provisionalReply = '';
try {
  const result = await client.chat({
    messages: [{ role: 'user', content: 'Explain why the sky looks blue.' }],
  }, {
    signal: AbortSignal.timeout(60_000),
    onDelta(text) {
      provisionalReply += text;
      // Your UI can show provisionalReply as an answer still in progress.
    },
  });
  console.log(result.reply); // Commit the answer only after chat resolves.
} catch (error) {
  provisionalReply = ''; // Discard an incomplete preview.
  throw error;
}
```

Each delta comes from an individually authenticated chunk, but the accumulated answer remains provisional. `chat` resolves only after the authenticated final result and clean end of the response have been verified. A truncated or tampered stream rejects even if some text was delivered. Do not save partial text as a completed answer or use it to trigger actions. The callback may return a promise, which the client awaits; throwing from it fails the request.

### Conversation history and limits

Send the history needed for the next answer on each call. The API client does not load or save conversations in the app. A follow-up can include the previous `{ role: 'user', content: ... }`, `{ role: 'assistant', content: result.reply }`, and a new user message.

- Send 1–64 messages, each with exactly `role` and `content`.
- Roles are `user` or `assistant`; content must be nonempty text. The last message must be from the user.
- All message content combined is limited to 12,000 JavaScript string code units (`content.length` summed across messages). Most ordinary characters count as one; some characters, including many emoji, count as two.
- The serialized chat payload must also fit within 64 KiB before encryption. JSON escaping and message structure count toward this bound; the client validates it before making a request.
- The server fixes the response cap at 1,024 output tokens. `system` messages, tools, images, `temperature`, and `max_tokens` are not supported by this interface.

Only these two model IDs are allowed. Availability also depends on the running service's provider catalog:

| Model | `model` / `--model` value |
| --- | --- |
| Gemma 4 26B A4B Uncensored (default) | `phala/gemma-4-26b-a4b-uncensored` |
| Qwen 3.8 27B Uncensored | `phala/qwen3.8-27b-uncensored` |

## Use the CLI

The default input is a single UTF-8 prompt on standard input:

```sh
node --env-file=.env.api scripts/account-chat.mjs \
  --policy approved.json \
  --url https://app.sideroom.sh \
  --model phala/gemma-4-26b-a4b-uncensored <<'PROMPT'
Explain public-key encryption in three short sentences.
PROMPT
```

`--policy` is required and accepts a JSON file up to 16 KiB. `--url` and `--model` use the same defaults as the JavaScript client. The CLI prints the completed answer to stdout, with terminal control characters removed. Gateway verification and retail billing diagnostics go to stderr. It does not stream text to the terminal.

Use `--messages` to read a JSON array of messages and `--json` to emit one structured result instead of plain answer text. These flags work independently. For example:

```sh
node --env-file=.env.api scripts/account-chat.mjs \
  --policy approved.json --messages --json <<'MESSAGES'
[
  { "role": "user", "content": "What is a public key?" },
  { "role": "assistant", "content": "A public key can be shared so others can encrypt messages to you." },
  { "role": "user", "content": "How is the private key different?" }
]
MESSAGES
```

`--json` writes one JSON object with `reply`, `model`, `usage`, `billing` when available, `finishReason`, and `transport` to stdout after success. Diagnostics stay on stderr, so stdout can be redirected to a file or parsed by another program. Failures exit with status 1 and do not emit a success object. JSON input is bounded to 128 KiB, and decoded messages must still satisfy the conversation limits above. Plain prompt input is bounded to 48,000 bytes and 12,000 string code units. Use `--help` for the command summary.

## Errors, billing and retries

Client validation and request failures use `SideroomError` with a machine-readable `code` and, when available, a numeric `status`. Handle the code rather than matching message text. Cancellation and timeouts use `AbortError` and `TimeoutError` names. An authenticated gateway operation error can also include `billing`, `usage`, and `transport`; account rejection or transport failures may have no such details.

| Code | Action |
| --- | --- |
| `key`, `url`, `preview`, `policy`, `model`, `messages`, `options` | Correct the client configuration or input. |
| `unauthorized`, `invalid_credential`, `account_required` | Check the key and whether it has been revoked; create a replacement in Settings if needed. |
| `insufficient_credits` | Add credits to the account that issued the key. |
| `account_busy`, `rate_limited` | Wait for the current request to finish or the rate limit to clear before submitting again. |
| `model_unavailable` | Choose another supported model or wait for availability. |
| `request_replayed` | Check the account before submitting another request. |
| `request_failed` or a provider failure | Treat completion and billing as uncertain until checked. |

Before inference, the account service reserves a maximum charge. Known usage settles the retail charge and releases the unused allowance. When `billing.usageKnown` is `false`, `chargedUnits` describes the conservative reservation retained because actual usage is unknown. One USD equals 1,000,000,000 credit units. Missing billing information or `usage.available: false` does not mean a free request.

The client never automatically retries inference or falls back to plaintext. A timeout, cancellation, network failure, or rejected stream may happen after the provider has started work and credits have been reserved or spent. Check the account balance and any authenticated billing result before choosing to submit again; do not wrap paid calls in an unconditional retry loop.

## Protocol and privacy boundary

The client uses `createGatewayClient` internally. A fresh `GET /api/lab/connection?nonce=<64 hex characters>` obtains gateway attestation bound to its challenge and encryption key. `POST /api/lab/secure` carries the OHTTP-encrypted request and response; streaming uses authenticated Chunked OHTTP. These are binary protocol endpoints, not an OpenAI-compatible JSON API.

The API key is sent to the Sideroom relay in `X-Sideroom-Account`; the selected model and UTF-8 input byte count are sent separately for billing. The relay sees account, model, size, timing and billing metadata, while prompt and reply content travel in the encrypted body. Your application, its runtime, and any custom `fetchImpl` are part of the trusted environment.

The approved gateway decrypts your messages and sends them over a separate HTTPS connection to the external model provider, which processes plaintext to generate the reply. Gateway verification does not independently establish provider GPU confidentiality or verify actual model weights. API calls do not grant access to the app's encrypted saved history.
