TypeScript SDK

The official TypeScript/JavaScript SDK for Runcrate. Zero runtime dependencies, native fetch, full type safety.

Installation

npm install @runcrate/sdk

Requires Node.js 18+.

Quick Start

import Runcrate from '@runcrate/sdk';

const rc = new Runcrate({ apiKey: 'rc_live_YOUR_API_KEY' });

// Chat completion
const response = await rc.models.chatCompletion({
  model: 'deepseek-ai/DeepSeek-V3',
  messages: [{ role: 'user', content: 'Hello!' }],
});
console.log(response.choices[0].message.content);

// List GPU instances
const instances = await rc.instances.list();
instances.forEach(i => console.log(`${i.name}: ${i.status}`));

You can also set the RUNCRATE_API_KEY environment variable instead of passing apiKey.

Configuration

const rc = new Runcrate({
  apiKey: 'rc_live_...',                       // or RUNCRATE_API_KEY env var
  baseUrl: 'https://www.runcrate.ai',              // infrastructure API
  inferenceUrl: 'https://api.runcrate.ai',     // model inference API
  timeout: 30,                                 // seconds
  maxRetries: 3,                               // retries; see Retries and launches below
  customHeaders: {},                           // extra headers
  environment: 'production',                   // optional: target a specific environment
});

Retries and launches

Reads, updates and deletes are retried on 429, 5xx, timeouts and lost connections, honouring Retry-After up to 60 seconds. A request that creates or launches something is never sent twice by accident:

Job submits and reruns send an Idempotency-Key (a new one per call, reused on its retries), which the server honours, so they are retried like reads: a retry after a timeout answers the first job.
Instance, schedule and volume creates also send an Idempotency-Key, but those routes do not deduplicate it yet; schedules.runNow sends none. Once one of these, or a run-now, may have reached Runcrate (a timeout, a lost connection, a 500, 502 or 504), it is not sent again and the error is thrown: check rc.instances.list() before launching again. Only a 429 or 503, which say nothing was launched, and a connection that never opened are retried.
A launch waits at least 75 seconds for its answer (a job submit 135), whatever timeout is, so the client does not give up while the server is still launching.
A 502 with code launch_refused is never retried: the same request is refused the same way.

Environments

API keys are workspace-scoped. By default, requests target the workspace’s default environment (usually main). Pass environment at client construction to target a different one:

// Default environment
const rc = new Runcrate({ apiKey: 'rc_live_...' });

// Specific environments
const staging = new Runcrate({ apiKey: 'rc_live_...', environment: 'staging' });
const prod    = new Runcrate({ apiKey: 'rc_live_...', environment: 'production' });

// Each client only sees resources in its own environment
await staging.instances.list();   // only staging instances
await prod.instances.list();      // only production instances

Environment-scoped: instances, crates, storage volumes. Workspace-wide: SSH keys, billing, API keys, templates.

Model Inference

All inference methods hit api.runcrate.ai.

Chat Completions

const response = await rc.models.chatCompletion({
  model: 'deepseek-ai/DeepSeek-V3',
  messages: [{ role: 'user', content: 'Explain quantum computing' }],
  maxTokens: 500,
  temperature: 0.7,
});
console.log(response.choices[0].message.content);

Streaming

const stream = await rc.models.chatCompletion({
  model: 'deepseek-ai/DeepSeek-V3',
  messages: [{ role: 'user', content: 'Tell me a story' }],
  stream: true,
});

for await (const chunk of stream) {
  const content = (chunk.choices as any[])?.[0]?.delta?.content ?? '';
  process.stdout.write(content);
}

Image Generation

const image = await rc.models.generateImage({
  model: 'black-forest-labs/FLUX.1-schnell',
  prompt: 'A futuristic cityscape at sunset',
  width: 1024,
  height: 768,
});

// Save directly: handles base64, data URIs, and URLs automatically
await image.save('output.webp');

Model-Specific Parameters

All inference methods accept extra parameters that get passed through to the model. Different models support different parameters:

// Seed for reproducibility
const image = await rc.models.generateImage({
  model: 'black-forest-labs/FLUX.1-schnell',
  prompt: 'A cat in space',
  seed: 42,
  numInferenceSteps: 4,
  guidance: 3.5,
});

// Image editing: pass a file path, URL, or base64 string
const edited = await rc.models.generateImage({
  model: 'black-forest-labs/FLUX.1-kontext-pro',
  prompt: 'Make the sky purple',
  image: './photo.png',              // file path (auto base64-encoded)
});

// Image editing with URL
const result = await rc.models.generateImage({
  model: 'Wan-AI/Wan2.6-Image-Edit',
  prompt: 'Remove the background',
  image: 'https://example.com/photo.png',  // URL (passed as-is)
});

The image, startImage, mask, and controlImage fields accept three formats:

File path: "./photo.png" (auto-detected, read and base64-encoded)
URL: "https://..." (passed through as-is)
Base64 string: raw base64 data (passed through as-is)

Video Generation

// Submit, poll, and save in one call
const job = await rc.models.generateVideoAndSave('output.mp4', {
  model: 'google/veo-3.0-audio',
  prompt: 'A drone flying over mountains',
  duration: 8,
  onStatus: (j) => console.log(`Status: ${j.status}`),
});

Or manage the lifecycle manually:

const job = await rc.models.generateVideo({
  model: 'google/veo-3.0-audio',
  prompt: 'Ocean waves at sunset',
});

// Poll until done
let status = job;
while (status.status !== 'completed' && status.status !== 'failed') {
  await new Promise(r => setTimeout(r, 5000));
  status = await rc.models.getVideoStatus(job.id);
}

// Download
const videoBuffer = await rc.models.downloadVideo(job.id);

Extra parameters (e.g., seed, negative_prompt, image for image-to-video) are passed through:

const job = await rc.models.generateVideo({
  model: 'some-img2vid-model',
  prompt: 'Animate this scene',
  image: './first_frame.png',   // image-to-video
  seed: 42,
  negative_prompt: 'blurry',
});

Text-to-Speech

// One-liner save
await rc.models.textToSpeechAndSave('speech.mp3', {
  model: 'hexgrad/Kokoro-82M',
  input: 'Hello from Runcrate!',
  voice: 'af_heart',
});

// Or get raw Buffer
const audio = await rc.models.textToSpeech({
  model: 'hexgrad/Kokoro-82M',
  input: 'Hello from Runcrate!',
  voice: 'af_heart',
});

Extra parameters like speed or language are passed through:

await rc.models.textToSpeechAndSave('speech.mp3', {
  model: 'hexgrad/Kokoro-82M',
  input: 'Hello!',
  voice: 'af_heart',
  speed: 1.5,           // model-specific
  language: 'en',       // model-specific
});

Transcription

import { readFile } from 'node:fs/promises';

const audioFile = await readFile('recording.wav');
const result = await rc.models.transcribe({
  model: 'openai/whisper-large-v3',
  file: audioFile,
  filename: 'recording.wav',
  language: 'en',              // optional hint; unrecognised values are ignored
  responseFormat: 'srt',       // json, verbose_json, text, srt, vtt
});
console.log(result.text);      // for text, srt and vtt: the transcript or subtitle file itself

Without responseFormat you get the full object: text, duration, language and timed segments (the same as verbose_json). json gives text only.

Infrastructure Management

GPU Instances

// List instances
const instances = await rc.instances.list();
const filtered = await rc.instances.list({ search: 'training' });

// Browse available GPU types
const types = await rc.instances.listTypes({ gpuType: 'A100' });
types.forEach(t => console.log(`${t.id}: ${t.gpuType} x${t.gpuCount}, $${t.hourlyRate}/hr`));

// Create an instance
const instance = await rc.instances.create({
  name: 'training-run',
  sshKeyId: 'your-key-id',
  gpuType: 'A100',
  gpuCount: 1,
  startupCommands: ['pip install torch'],
  maxRuntimeMinutes: 240,    // terminate 4 hours after it starts running (5 to 10080)
  idleShutdownMinutes: 30,   // terminate after 30 idle minutes (5 to 1440)
});
console.log(`Created: ${instance.id}: ${instance.status}`);

// Check status
const status = await rc.instances.getStatus(instance.id);
console.log(`Status: ${status.status}, IP: ${status.ip}`);

// Guardrails, once it is running
const current = await rc.instances.get(instance.id);
console.log(current.maxRuntimeMinutes, current.idleShutdownMinutes);
console.log(`Stops at: ${current.autoStopAt}`); // null without a max runtime

// Extend before a long job (total minutes from when it started); null turns a limit off
await rc.instances.update(instance.id, { maxRuntimeMinutes: 480, idleShutdownMinutes: null });

// Terminate
await rc.instances.terminate(instance.id);

maxRuntimeMinutes and idleShutdownMinutes are optional and off when omitted. After an instance stops, stopReason (type InstanceStopReason) says why: user, max_runtime, idle, budget, low_balance, failed or system. See Spend guardrails.

Environment Budgets

const env = await rc.environments.get('environment-id');
console.log(`Budget: ${env.monthlyBudgetUsd}`);           // null means no cap
console.log(`Spent this month: ${env.monthToDateUsd}`);   // UTC calendar month, instances plus inference
console.log(`Remaining: ${env.budgetRemainingUsd}`);      // null means no cap

The SDK reads budgets but cannot set them: a workspace owner or admin sets them in the dashboard. Once an environment reaches its budget, launches in it throw InsufficientCreditsError with err.code === 'BUDGET_REACHED'.

Schedules

A schedule starts an instance or a job later. Pass exactly one of runAt (once) or cron (repeating, read in timezone). spec is the create body of the kind, and maxRuntimeMinutes is required in it.

// A job every night at 02:00 London time
const schedule = await rc.schedules.create({
  kind: 'job',
  name: 'nightly-train',
  cron: '0 2 * * *',
  timezone: 'Europe/London',
  spec: { command: 'python train.py', gpuType: 'H100', maxRuntimeMinutes: 120 },
});
console.log(`Next run: ${schedule.nextRunAt}`);

// An instance once, at a set time
await rc.schedules.create({
  kind: 'instance',
  runAt: new Date('2026-10-21T09:00:00-04:00'),
  timezone: 'America/New_York',
  spec: { name: 'demo-box', gpuType: 'A100', maxRuntimeMinutes: 480 },
});

// List, inspect, pause, resume
const schedules = await rc.schedules.list();
const s = await rc.schedules.get(schedule.id);
console.log(s.lastStatus, s.lastError, s.runCount);
await rc.schedules.update(schedule.id, { enabled: false });
await rc.schedules.update(schedule.id, { enabled: true });

// Launch once now, then delete
const { job } = await rc.schedules.runNow(schedule.id);
await rc.schedules.delete(schedule.id);

Jobs

A job runs one command on its own fresh GPU machine, which stops (and stops billing) when the command ends. Files the command writes to $RUNCRATE_OUTPUT_DIR are kept 30 days.

import { basename } from 'node:path';

const job = await rc.jobs.run({
  command: 'python train.py --epochs 3 && cp model.pt $RUNCRATE_OUTPUT_DIR/',
  gpuType: ['A4000', 'L40S'],       // tried in order; an entry may carry its count, 'H100:2'
  maxRuntimeMinutes: 60,            // required, 1 to 10080; each attempt stops after this long
  template: 'ubuntu-train',
  env: { HF_TOKEN: process.env.HF_TOKEN! },
  tags: { project: 'vision' },      // sent and returned exactly as written
  maxRetries: 2,                    // retries a machine failure; add retryOn: ['nonzero_exit'] for the command's own
  code: { git: { url: 'https://github.com/acme/train', ref: 'main' } },
});

// The output as it is written, until the job ends
for await (const chunk of rc.jobs.followLogs(job.id)) process.stdout.write(chunk.text);

// Polls with a doubling gap (2 s to 30 s); throws JobWaitTimeoutError past the timeout, and the job keeps running
const done = await rc.jobs.wait(job.id, { timeout: 3600 });
console.log(done.status, done.exitCode, done.costUsd);

for (const file of await rc.jobs.artifacts.list(job.id)) {
  await rc.jobs.artifacts.downloadTo(job.id, file.path, basename(file.path));
}

Send local code with const upload = await rc.jobs.uploads.upload('./code.tar.gz') (a path to a tar.gz, or its bytes, at most 1 GB) and run with code: { uploadId: upload.uploadId } within 24 hours. The command runs in /workspace/code.

Method	What it does
`jobs.run(params, { idempotencyKey? })`	Runs one job.
`jobs.runGroup({ ...params, count, maxParallel })` or `{ ...params, params: [...] }`	Runs `count` copies, or one job per `params` entry (each merged over `env`), at most `maxParallel` at once. Answers the group with its jobs. See Arrays.
`jobs.get(id)`	One job: status, attempts, exit code, cost, tags, code, `artifactsCount`, GPU use.
`jobs.list({ status, tags, groupId, q, gpuType, createdAfter, limit, cursor })`	One page of jobs, newest first (`hasMore`, `cursor`). `jobs.listAll(filters)` pages through.
`jobs.cancel(id)`	Stops the job’s machine; the job becomes `cancelled`.
`jobs.delete(id)`	Deletes a job that ended, with its logs and outputs (a live one throws `ConflictError`).
`jobs.rerun(id, overrides?)`	Runs the spec again as a new job with its env values; `overrides.env` is merged over them.
`jobs.logs(id, { after, limit, follow })`	One page of output; pass `cursor` back as `after`.
`jobs.followLogs(id, { after, signal })`	Every chunk as it is written, until the job ends.
`jobs.events(id)`	The timeline: queued, launch attempts, machine up, started, exited, retrying, stopped.
`jobs.metrics(id, { step })`	GPU use while the command ran, one point per `step` seconds.
`jobs.wait(id, { timeout, pollInterval, maxPollInterval })`	Polls until the job ends and answers it.
`jobs.artifacts.list(id)`, `.url(id, path)`, `.download(id, path)`, `.downloadTo(id, path, file)`	The outputs; `url` is a signed link valid an hour. The API key is never sent to it.
`jobs.uploads.upload(archive)`	Sends a tar.gz of your code.
`jobGroups.get(id)`, `jobGroups.cancel(id)`	A group’s counts per status and its cost; cancels its live jobs.

Pass your own idempotencyKey to make a submit safe to repeat across processes: the same key with the same request answers the first job for 24 hours (see Idempotency). A low balance throws InsufficientCreditsError, a reached environment budget the same with code BUDGET_REACHED, and a bad field UnprocessableEntityError.

Secrets

The names of the secrets every machine in the client’s environment gets. Values are set in the dashboard and never returned. A value passed for one launch (envVars) wins over a secret of the same name.

for (const secret of await rc.secrets.list()) {
  console.log(secret.key, secret.sensitive, secret.updatedAt);
}

SSH Keys

// List keys
const keys = await rc.sshKeys.list();

// Add a key
const key = await rc.sshKeys.create({
  name: 'my-laptop',
  publicKey: 'ssh-ed25519 AAAA...',
});

// Delete a key
await rc.sshKeys.delete(key.id);

Storage

Storage volumes are environment-scoped. Your workspace’s storage must be set up in the dashboard first; the SDK picks it up automatically.

// List available regions (with friendly names)
const regions = await rc.storage.listRegions();
regions.forEach(r => console.log(`${r.name} (${r.provider})`));

// List volumes in the current environment
const volumes = await rc.storage.list();
const filtered = await rc.storage.list({ search: 'datasets' });

// Get a specific volume
const volume = await rc.storage.get('volume-id');

// Create a 100GB volume
const created = await rc.storage.create({
  name: 'datasets',
  sizeGb: 100,
  region: 'us-east-1',
});

// Launch an H100 with the volume attached (files in /workspace)
const instance = await rc.instances.create({
  name: 'training-run',
  sshKeyId: 'your-key-id',
  gpuType: 'H100',
  storageId: created.id,
});

// Resize (increase capacity only)
await rc.storage.resize(created.id, 200);

// Delete (refunds unused prepaid days pro-rata)
const result = await rc.storage.delete(created.id);
console.log(`Refunded $${result.refundAmount}`);

Billing: $0.03/GB/month, charged weekly in advance. Deletion refunds the unused portion of the current billing week.

Billing

// Check balance
const balance = await rc.billing.getBalance();
console.log(`Credits: $${balance.creditsBalance}`);

// List transactions (paginated)
const txns = await rc.billing.listTransactions({ limit: 20 });
txns.data.forEach(t => console.log(`${t.type}: $${t.amount}`));
console.log(`Has more: ${txns.hasMore}`);

// Usage summary
const usage = await rc.billing.usage({ from: '2025-01-01', to: '2025-01-31' });
console.log(`Total cost: $${usage.totalCost}`);

Templates

// List templates with search
const templates = await rc.templates.list({
  search: 'finetune',
  category: 'ml',
  page: 1,
  pageSize: 10,
});
templates.data.forEach(t => console.log(`${t.name}: ${t.category}`));
console.log(`Total: ${templates.total}`);

Error Handling

All API errors include the actual error message from the server, never a generic fallback.

import {
  NotFoundError,
  AuthenticationError,
  RateLimitError,
  InsufficientCreditsError,
  BadRequestError,
  UnprocessableEntityError,
} from '@runcrate/sdk';

try {
  await rc.instances.get('nonexistent');
} catch (err) {
  if (err instanceof NotFoundError) {
    console.log(`Not found: ${err.message}`);
  } else if (err instanceof AuthenticationError) {
    console.log('Invalid API key');
  } else if (err instanceof RateLimitError) {
    console.log('Rate limited, retry later');
  } else if (err instanceof InsufficientCreditsError) {
    console.log(
      err.code === 'BUDGET_REACHED'
        ? `Environment budget reached: ${err.message}`
        : `Not enough credits: ${err.message}`,
    );
  } else if (err instanceof UnprocessableEntityError) {
    console.log(`Validation error: ${err.message}`);  // e.g. invalid model params
  } else if (err instanceof BadRequestError) {
    console.log(`Bad request: ${err.message}`);
  }
}

Every error exposes:

err.message: human-readable error description from the API
err.statusCode: HTTP status code
err.code: machine-readable error code (e.g. not_found, rate_limited)
err.details: additional details (when available)

Error Hierarchy

Exception	Status Code	Description
`BadRequestError`	400	Invalid parameters
`AuthenticationError`	401	Invalid or missing API key
`InsufficientCreditsError`	402	Not enough credits, or the environment’s monthly budget is reached (`code` is `BUDGET_REACHED`)
`PermissionDeniedError`	403	Insufficient permissions
`NotFoundError`	404	Resource not found
`ConflictError`	409	Resource conflict
`UnprocessableEntityError`	422	Validation error (e.g. invalid model params)
`RateLimitError`	429	Rate limit exceeded
`InternalServerError`	500	Server error
`ConnectionError`	None	Network failure
`TimeoutError`	None	Request timed out

Welcome

SDKs

CLI

Inference

Compute

Jobs

Schedules

Secrets

Storage

Dedicated Clusters

Billing

Account

Webhooks

FAQ

Installation

Quick Start

Configuration

Retries and launches

Environments

Model Inference

Chat Completions

Streaming

Image Generation

Model-Specific Parameters

Video Generation

Text-to-Speech

Transcription

Infrastructure Management

GPU Instances

Environment Budgets

Schedules

Jobs

Secrets

SSH Keys

Storage

Billing

Templates

Error Handling

Error Hierarchy

​Installation

​Quick Start

​Configuration

​Retries and launches

​Environments

​Model Inference

​Chat Completions

​Streaming

​Image Generation

​Model-Specific Parameters

​Video Generation

​Text-to-Speech

​Transcription

​Infrastructure Management

​GPU Instances

​Environment Budgets

​Schedules

​Jobs

​Secrets

​SSH Keys

​Storage

​Billing

​Templates

​Error Handling

​Error Hierarchy

Installation

Quick Start

Configuration

Retries and launches

Environments

Model Inference

Chat Completions

Streaming

Image Generation

Model-Specific Parameters

Video Generation

Text-to-Speech

Transcription

Infrastructure Management

GPU Instances

Environment Budgets

Schedules

Jobs

Secrets

SSH Keys

Storage

Billing

Templates

Error Handling

Error Hierarchy