TypeScript SDK

Use the SDK when your agent application needs to manage compute directly rather than shelling out to the CLI.

Install the SDK on Node.js 22 or later:

npm install @openmetal/sdk

The package validates API responses at runtime, applies request timeouts, retries safe GET requests, and creates idempotency keys for supported mutations.

Project client

import { MetalClient } from "@openmetal/sdk";

const metal = new MetalClient({
  baseUrl: process.env.OPENMETAL_API_URL!,
  projectId: process.env.OPENMETAL_PROJECT_ID!,
  accessToken: () => process.env.OPENMETAL_API_KEY,
  timeoutMs: 10_000,
  retry: {
    attempts: 2,
    backoffMs: 100,
  },
});

Main namespaces

• sandboxes manages lifecycle.
• operations waits for lifecycle mutations and reads events.
• processes creates commands, reads status, streams events, and requests cancellation.
• filesystem reads, writes, lists, deletes, uploads, and downloads.
• runtimeOperations waits for filesystem work.
• endpoints creates, lists, and revokes HTTP leases.
• organizations, projects, apiKeys, members, invitations, providerCredentials, billing, usage, webhooks, and events use an OpenMetal user access token.

Errors and retries

MetalError exposes status, code, details, a request ID, and whether the error is retryable. RuntimeOperationWaitError preserves the runtime operation and idempotency key when a file upload has an uncertain result.

The client retries safe GET requests only. A mutation error can expose its original idempotencyKey. Application code must decide whether replay is safe and reuse that exact key with identical input.