# TypeScript SDK (/sdk-and-cli/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:

```bash
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 [#project-client]

```ts
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 [#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 [#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.

<Cards>
  <Card title="TypeScript quickstart" href="/get-started/typescript" />

  <Card title="Run a process" href="/guides/run-process" />

  <Card title="Common errors" href="/errors/common-errors" />
</Cards>