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

Installation

Requires Node.js 18+.

Quick Start

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

Configuration

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:
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

Streaming

Image Generation

Model-Specific Parameters

All inference methods accept extra parameters that get passed through to the model. Different models support different parameters:
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

Or manage the lifecycle manually:
Extra parameters (e.g., seed, negative_prompt, image for image-to-video) are passed through:

Text-to-Speech

Extra parameters like speed or language are passed through:

Transcription

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

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

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.

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.
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. 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.

SSH Keys

Storage

Storage volumes are environment-scoped. Your workspace’s storage must be set up in the dashboard first; the SDK picks it up automatically.
Billing: $0.03/GB/month, charged weekly in advance. Deletion refunds the unused portion of the current billing week.

Billing

Without idempotencyKey, topUp makes a UUID and returns it on the answer. See Top up by API for the permission, caps and statuses.

Templates


Error Handling

All API errors include the actual error message from the server, never a generic fallback.
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