@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. Two capabilities today: runtime.ai.* for platform AI, and runtime.call for app-to-app calls.

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>
runtime.call(address, path?, init?): Promise<Response>

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.

App-to-app calls

runtime.call reaches another app on the grid. The model (Decision 051): an app is callable by another app only if the callee has granted the caller. The grant is enforced by the callee's network policy, so there is no token to carry and nothing injected into your environment — the address resolves at call time and the request is a plain fetch. RUNTIME_GATEWAY_URL is the only env var this uses, and the platform injects it into every service; runtime.call needs no requires:/needs: entry.

Declare the relationship

The caller lists what it calls; the callee lists who may call it.

# caller's cloudgrid.yaml
calls:
  - todo-api            # an app in this grid (the common case)
  - qa-todo/todo-api    # <grid-slug>/<app-slug> (same-grid only in this release)
  - 42f6e1c3-...        # or the entity id, stable across renames

# callee's cloudgrid.yaml
callers:
  scope: explicit
  allowed_apps:
    - todo-viewer   # named callers are granted at the caller's plug
  # policy: auto    # or: grant every same-grid caller (a deliberate opt-in)
  # policy: manual  # or: every grant waits for admin approval in Console

The default is deny. A caller not named in allowed_apps (and not covered by policy: auto) is born requested and waits for the callee admin's approval in Console. Approve or revoke takes effect live — the caller does not re-plug. Membership in a grid grants nothing on its own; only an explicit grant does.

Make the call

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

const res = await runtime.call('todo-api', '/todos');
if (res.ok) {
  const todos = await res.json();
}

runtime.call(address, path?, init?) returns a standard Response:

• address — the same three forms calls: accepts (app slug, <grid-slug>/<app-slug>, or entity id).
• path — appended to the callee's internal URL; omit it to hit the root.
• init — a standard RequestInit, passed to fetch untouched. The SDK sets no header of its own, so Authorization stays free for your app's own protocol.

The Response comes back as-is: an HTTP error status is the callee's answer, not an SDK failure. runtime.call throws only when the call cannot be made — see Errors below. It works inside a deployed app; on a developer machine it throws GridError CALLER_NOT_CONFIGURED, so plug the app with grid plug and call other apps from there.

Calling from a non-JS runtime

runtime.call is a thin wrapper over one platform request plus a plain fetch. A Python or Go app does the same two steps directly.

1. Resolve the address. The platform injects RUNTIME_GATEWAY_URL into every service and mounts the pod identity token at /var/run/cloudgrid/identity/token.

   GET ${RUNTIME_GATEWAY_URL}/app-connection/resolve?address=todo-api
   Authorization: Bearer <contents of /var/run/cloudgrid/identity/token>
   

   On success the response is 200 with { "url": "http://<svc>-app.<namespace>.svc.cluster.local", "entity_id": "<uuid>" }. Cache the url — the SDK reuses it for about 5 minutes, and the in-cluster name is stable across re-plugs. The endpoint requires the signed pod token; the legacy X-CloudGrid-* identity headers are rejected. Failure statuses:

   Status	code	Meaning
   401	MISSING_IDENTITY / IDENTITY_TOKEN_REQUIRED	No bearer token, or the legacy header path was used.
   401	IDENTITY_EXPIRED	Token rotated; wait (Retry-After: 60) and retry.
   403	CALL_NOT_GRANTED	This app is not granted, or the grant is still pending. fix names the next step.
   404	CALLER_TARGET_NOT_FOUND / CALLEE_NOT_ROUTABLE	The target does not exist in this grid, or has no callable service.
   400	CALLER_INVALID_ADDRESS / CROSS_GRID_NOT_SUPPORTED	Malformed address, or a cross-grid target (not supported this release).

2. Call the resolved URL with a plain request — no auth header from the platform. The callee's network policy already decided you may connect.

   GET <url>/todos
   

Errors

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

GridError is the base grid error for the runtime surface; it carries code (string), status (HTTP status), and an optional fix (an actionable next step). 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.

runtime.call throws GridError with one of two codes when the call cannot be made: CALLER_NOT_CONFIGURED when the address cannot be resolved (this app is not granted, the target does not exist, or the address is malformed), and CALLEE_UNREACHABLE when the address resolved but the connection failed (the callee is down, or its admin removed this app from its callers). A non-2xx HTTP status is not an error — it is returned on the Response.

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.
• App Connection contract — the full runtime.call reference: model, resolve endpoint, error codes.
• Decision 014 — Runtime SDK identity model — why identity is platform-resolved, not caller-supplied.
• Decision 051 — App Connection — declared callers, network-enforced.
• CLI — @cloudgrid-io/cli.