@cloudgrid-io/runtime

The Runtime SDK for CloudGrid. Zero-config access to platform services from inside any entity on the grid — no API keys in your code. AI is the first capability: runtime.ai.*.

This package supersedes @cloudgrid-io/ai. AI now lives under runtime.ai. The old package name still works (it re-exports this one), so existing entities keep running with no code change.

Install

npm install @cloudgrid-io/runtime

Prerequisite

Add ai to the requires: block of your cloudgrid.yaml:

name: my-app
services:
  api:
    type: node
    path: /
requires:
  - ai

The platform injects RUNTIME_GATEWAY_URL at runtime — the SDK's only gateway env var. The SDK resolves identity internally — your code does not see a token, and never sees or handles a provider key.

Use

import { runtime } from '@cloudgrid-io/runtime';

// Chat
const { text } = await runtime.ai.chat({
  prompt: 'Summarize this report: ...',
  model: 'claude-haiku',
});

// Generate (single prompt)
const out = await runtime.ai.generate({ prompt: 'Write a haiku' });

// Vision
const image = await readFile('./screenshot.png');
const desc = await runtime.ai.vision({ image, prompt: 'What is in this image?' });

// Embeddings — for search and RAG
const vec = await runtime.ai.embeddings({ text: 'hello world' });
// vec.values : number[] (1536 for the default model)
// vec.model, vec.dim, vec.tokens

// Batch embeddings — preserves input order
const vecs = await runtime.ai.embeddings({ text: ['a', 'b', 'c'] });

// Streaming chat
for await (const chunk of runtime.ai.chat({ prompt, stream: true })) {
  if (chunk.type === 'text') process.stdout.write(chunk.text);
}

The SDK takes no identity argument. It reads identity from one of two places:

• inside a CloudGrid pod, the platform-mounted identity file at /var/run/cloudgrid/identity/token
• on a developer machine, ~/.cloudgrid/credentials plus <cwd>/.cloudgrid/link.json

Outside both, the first call throws IdentityNotFoundError.

Platform vs bring-your-own

Every AI service (chat, image, embeddings) carries a per-Grid provider decision, set by a Grid admin in the Console under Grid settings → Services:

• Platform (default) — the call runs on the platform's key; usage is metered to the Grid.
• Bring your own — the call runs on the Grid's own key (stored encrypted in the Grid Vault); the platform meters usage but does not bill for it.

Your code does not change. The same line runs on platform tokens or the Grid's key depending on one switch in the Grid's settings. The key never leaves the server.

Managed substrate — don't reach for a personal key

If you need embeddings, use runtime.ai.embeddings. Do not install a personal OpenAI key or a third-party vector service — the platform provides the model and (when the Grid opts in) meters the spend. The default embedding model is 1536-dimensional, matching the platform's managed pgvector.

Methods

runtime.ai.chat(req): Promise<AIResponse>
runtime.ai.chat({ ...req, stream: true }): AsyncGenerator<StreamChunk>
runtime.ai.generate(req): Promise<AIResponse>
runtime.ai.vision(req): Promise<AIResponse>
runtime.ai.embeddings({ text: string }): Promise<EmbeddingVector>
runtime.ai.embeddings({ text: string[] }): Promise<EmbeddingVector[]>
runtime.ai.image(req): Promise<ImageResponse>

interface AIResponse {
  text: string;
  model: string;
  usage: { input_tokens: number; output_tokens: number };
}

interface EmbeddingVector {
  values: number[];
  model: string;
  dim: number;
  tokens: number;
}

Models

Pass model: as one of the gateway aliases — claude-haiku (fast), claude-sonnet (default), claude-opus (highest capability) — and the gateway resolves it server-side. Embeddings default to text-embedding-3-small. The gateway enforces a server-side model whitelist.

Errors

import {
  GridError,
  GridAIError,
  IdentityNotFoundError,
  MalformedIdentityError,
} from '@cloudgrid-io/runtime';

GridError is the base grid error for the runtime surface; it carries code (string) and status (HTTP status). GridAIError is the subclass thrown by runtime.ai.* calls. CloudGridAIError is still exported as a deprecated alias of GridAIError, so existing instanceof CloudGridAIError catches keep working. IdentityNotFoundError is thrown when neither in-grid nor dev identity is available; MalformedIdentityError is thrown when the identity file or link.json exists but cannot be parsed.

Compatibility

@cloudgrid-io/[email protected] re-homes the AI SDK under runtime.ai. The top-level createClient(), the legacy ai singleton, and createLegacyClient() are still exported for back-compat. The deprecated @cloudgrid-io/ai package re-exports everything here, so existing imports keep working.

More

• AI Gateway docs — gateway contract: modes, budgets, model aliases.
• Decision 014 — Runtime SDK identity model — why identity is platform-resolved, not caller-supplied.
• CLI — @cloudgrid-io/cli.