# TypeScript SDK

> Every method and option of the Sandscale TypeScript SDK (@sandscale/sdk 0.2.0), generated from its source.

@sandscale/sdk 0.2.0. Every method and option, generated from the SDK source.

[SDK overview](https://sandscale.dev/docs/sdks) · [Errors](https://sandscale.dev/docs/api/errors) · [Regions](https://sandscale.dev/docs/concepts/regions)

## Client

```sh
npm install @sandscale/sdk

import { Sandscale } from '@sandscale/sdk';
const sandscale = new Sandscale({ apiKey: process.env.SANDSCALE_API_KEY });
```

Create one client and reuse it. Its methods are grouped by area below. Every call also takes a `region`.

## `sandscale.sandboxes`

### `create`

```
sandscale.sandboxes.create(options: CreateSandboxOptions = {}): Promise<Sandbox>
```

Starts a sandbox. Limits, entitlement and policy are decided by the server.

### `get`

```
sandscale.sandboxes.get(id: string, options: CallOptions = {}): Promise<Sandbox>
```

### `list`

```
sandscale.sandboxes.list(options: ListSandboxesOptions = {}): Promise<ListResult<Sandbox>>
```

Lists sandboxes: of one region when one is named, else of every live region.

### `stop`

```
sandscale.sandboxes.stop(id: string, options: CallOptions = {}): Promise<void>
```

Stops the sandbox and releases it.

### `pause`

```
sandscale.sandboxes.pause(id: string, options: CallOptions = {}): Promise<{ id: string; status: string }>
```

Pauses a microVM sandbox (409 pause_unsupported for a container sandbox).

### `resume`

```
sandscale.sandboxes.resume(id: string, options: CallOptions = {}): Promise<{ id: string; status: string }>
```

### `snapshot`

```
sandscale.sandboxes.snapshot(id: string, options: CallOptions & { label?: string } = {}): Promise<Snapshot>
```

Snapshots the sandbox's /workspace. Start a new sandbox from it with `create({snapshotId})`.

### `listSnapshots`

```
sandscale.sandboxes.listSnapshots(id: string, options: CallOptions = {}): Promise<Snapshot[]>
```

The snapshots of one sandbox.

### `run`

```
sandscale.sandboxes.run(id: string, command: string[] | string, options: RunOptions = {}): Promise<RunResult>
```

Runs a command and returns its exit code and output. With `onStdout` or `onStderr` the command is started without waiting (`wait: false`): the server answers with its run id at once and the output is delivered live from that run's log stream, the exit code from the stream's end. A server that answers with the finished result instead (a server before `wait`, or a sandbox without live output) gets the callbacks the final output once (`streamed: false`).

### `logs`

```
sandscale.sandboxes.logs(id: string, runId: string, options: CallOptions & { fromChunk?: number; onDone?: (end: RunEnd) => void } = {}): AsyncGenerator<OutputChunk>
```

Streams a run's output (Server-Sent Events), resuming after a dropped connection.

### `writeFile`

```
sandscale.sandboxes.writeFile(id: string, path: string, data: Uint8Array | string, options: CallOptions & { mode?: string } = {}): Promise<void>
```

Writes a file into the sandbox (at most what the server accepts per request).

### `readFile`

```
sandscale.sandboxes.readFile(id: string, path: string, options: CallOptions = {}): Promise<Uint8Array>
```

Reads a file from the sandbox.

### `listFiles`

```
sandscale.sandboxes.listFiles(id: string, path: string, options: CallOptions = {}): Promise<FileEntry[]>
```

## `sandscale.workspaces`

### `list`

```
sandscale.workspaces.list(options: ListWorkspacesOptions = {}): Promise<ListResult<Workspace>>
```

Lists workspaces: of one region when one is named, else of every live region.

### `get`

```
sandscale.workspaces.get(id: string, options: CallOptions = {}): Promise<Workspace>
```

### `start`

```
sandscale.workspaces.start(id: string, options: CallOptions = {}): Promise<WorkspaceBuild>
```

Queues a start build.

### `stop`

```
sandscale.workspaces.stop(id: string, options: CallOptions = {}): Promise<WorkspaceBuild>
```

Queues a stop build.

### `connectInfo`

```
sandscale.workspaces.connectInfo(id: string, options: CallOptions = {}): Promise<ConnectInfo>
```

How to connect: SSH host and command, port forwarding, editor links, as the server allows.

## `sandscale.buildHosts`

### `listPools`

```
sandscale.buildHosts.listPools(options: CallOptions = {}): Promise<ListResult<Pool>>
```

The pools the caller can see, of one region or of every live region.

### `list`

```
sandscale.buildHosts.list(options: CallOptions & { scope?: 'mine' | 'org'; state?: string; limit?: number } = {}): Promise<ListResult<Lease>>
```

The caller's leases (`scope: 'org'` for every lease, where the server allows it).

### `get`

```
sandscale.buildHosts.get(leaseId: string, options: CallOptions = {}): Promise<Lease>
```

### `start`

```
sandscale.buildHosts.start(poolId: string, options: StartLeaseOptions = {}): Promise<Lease>
```

Takes a build host lease from a pool (it may wait for an approval: state `pending_approval`).

### `stop`

```
sandscale.buildHosts.stop(leaseId: string, options: CallOptions = {}): Promise<Lease>
```

Releases the lease; its host is wiped and deleted by the server.

### `connectInfo`

```
sandscale.buildHosts.connectInfo(leaseId: string, options: CallOptions = {}): Promise<LeaseConnectInfo>
```

How to reach the lease's host: its workspace's connect info, or a lab host's SSH relay.

### `sshCertificate`

```
sandscale.buildHosts.sshCertificate(leaseId: string, publicKey: string, options: CallOptions = {}): Promise<SSHCertificate>
```

A short-lived SSH certificate for the lease's host, for your public key.

## Types

### CallOptions

Options every call accepts.

| Field | Type | Description |
| --- | --- | --- |
| `region` optional | `Region` | The region to send this call to; overrides the client's region. |
| `signal` optional | `AbortSignal` | Aborts the call. |

### ClientOptions

| Field | Type | Description |
| --- | --- | --- |
| `apiKey` optional | `string` | A Sandscale API key. Default: $SANDSCALE_API_KEY. Give this or `token`. |
| `token` optional | `TokenSource` | The person's own sign-in access token, or a function returning a current one. |
| `baseUrl` optional | `string` | Default: $SANDSCALE_BASE_URL, else https://api.sandscale.dev. |
| `orgId` optional | `string` | Organization id: sent as X-Org-ID and used by the workspace and build host routes. Default: $SANDSCALE_ORG_ID. |
| `region` optional | `Region` | Region of every call that does not name one ("us" \| "eu"). Without it calls go to `baseUrl`. |
| `regionUrls` optional | `Record<string, string>` | Explicit API URL per region, instead of the server's public region list. |
| `timeoutMs` optional | `number` | Per-request timeout in milliseconds (default 60 000). |
| `maxRetries` optional | `number` | Retries of safe (GET) calls after a connection error, 429, 502, 503 or 504 (default 2). |
| `fetch` optional | `typeof globalThis.fetch` | A fetch implementation (tests, proxies). Default: globalThis.fetch. |

### ConnectInfo

| Field | Type | Description |
| --- | --- | --- |
| `sshHost` | `string` |   |
| `sshCommand` optional | `string` |   |
| `portForwardCommand` optional | `string` |   |
| `folder` optional | `string` |   |
| `sshReady` | `boolean` |   |
| `sshUnavailableReason` optional | `string` |   |
| `sshNote` optional | `string` |   |
| `links` | `{ ide: string; kind: string; url: string; requires?: string[] }[]` |   |
| `raw` | `Raw` |   |

### CreateSandboxOptions

| Field | Type | Description |
| --- | --- | --- |
| `template` optional | `string` | A template id of the organization, or a built-in ("builtin:base", "builtin:python", ...). |
| `snapshotId` optional | `string` | Start from a snapshot instead. |
| `cpuCount` optional | `number` | Size; with a template, nonzero values must match it (the server checks). |
| `memoryMb` optional | `number` |   |
| `diskMb` optional | `number` |   |
| `timeoutSeconds` optional | `number` | Seconds until the sandbox stops (server default 3600, at most 86400). |
| `env` optional | `Record<string, string>` | Plain environment variables. |
| `vaultEnv` optional | `VaultEnvRef[]` | Vault values for the sandbox's environment (`vault_env`): the server reads each as the caller (Vault's capabilities and audit) and hands it to the sandbox only. The values never pass through the SDK, the answer or an audit entry. |
| `command` optional | `string[]` |   |
| `name` optional | `string` |   |
| `labels` optional | `Record<string, string>` |   |
| `metadata` optional | `Record<string, string>` | `metadata.project_id` runs the sandbox in a project. |

### ErrorExtra

| Field | Type | Description |
| --- | --- | --- |
| `requestId` optional | `string` |   |
| `details` optional | `unknown` |   |
| `region` optional | `string` |   |
| `retryAfterMs` optional | `number` |   |

### FileEntry

| Field | Type | Description |
| --- | --- | --- |
| `path` | `string` |   |
| `name` | `string` |   |
| `isDir` | `boolean` |   |
| `size` optional | `number` |   |

### Lease

| Field | Type | Description |
| --- | --- | --- |
| `id` | `string` |   |
| `poolId` | `string` |   |
| `state` | `string` |   |
| `size` optional | `{ name: string; cpuCores: number; memoryGb: number }` |   |
| `purpose` optional | `string` |   |
| `repo` optional | `string` |   |
| `workspaceId` optional | `string` | The lease's host is this cloud workspace (cloud and BYOC pools). |
| `labHostId` optional | `string` | The lease's host is this lab host. |
| `host` optional | `{ status: string; ready: boolean; sshUser?: string }` |   |
| `createdAt` optional | `Date` |   |
| `expiresAt` optional | `Date` |   |
| `endedAt` optional | `Date` |   |
| `endReason` optional | `string` |   |
| `raw` | `Raw` |   |

### LeaseConnectInfo

| Field | Type | Description |
| --- | --- | --- |
| `lease` | `Lease` |   |
| `kind` | `'workspace' \| 'lab' \| 'pending'` | `workspace`: connect like a workspace; `lab`: SSH through the lease's relay WebSocket. |
| `workspace` optional | `ConnectInfo` |   |
| `sshRelayPath` optional | `string` | For a lab lease: the relay path (WebSocket, binary SSH) on the region's API origin. |
| `sshUser` optional | `string` |   |

### ListResult

| Field | Type | Description |
| --- | --- | --- |
| `data` | `T[]` |   |
| `pages` | `RegionPage[]` |   |

### ListSandboxesOptions

| Field | Type | Description |
| --- | --- | --- |
| `status` optional | `string` |   |
| `projectId` optional | `string` |   |
| `limit` optional | `number` |   |
| `cursor` optional | `string` | A cursor of one region's page; needs `region`. |

### ListWorkspacesOptions

| Field | Type | Description |
| --- | --- | --- |
| `limit` optional | `number` |   |
| `cursor` optional | `string` |   |
| `all` optional | `boolean` | Include deleted workspaces. |

### OutputChunk

| Field | Type | Description |
| --- | --- | --- |
| `stream` | `OutputStream` |   |
| `data` | `string` |   |
| `chunkIndex` | `number` |   |

### Pool

| Field | Type | Description |
| --- | --- | --- |
| `id` | `string` |   |
| `name` | `string` |   |
| `backend` | `string` |   |
| `sizes` | `{ name: string; cpuCores: number; memoryGb: number }[]` |   |
| `defaultSize` optional | `string` |   |
| `requiresApproval` | `boolean` |   |
| `raw` | `Raw` |   |

### RegionPage

One region's page of a list: lists without a region read every live region (decision 9).

| Field | Type | Description |
| --- | --- | --- |
| `region` optional | `Region` |   |
| `nextCursor` optional | `string` |   |
| `hasMore` | `boolean` |   |
| `error` optional | `SandscaleError` | Set when this region could not be read; the other regions' items are still returned. |

### Regional

Every resource says which region it lives in, so later calls on it go there.

| Field | Type | Description |
| --- | --- | --- |
| `region` optional | `Region` | The region the call went to (undefined: the client's base URL, no region named). |

### RequestSpec

| Field | Type | Description |
| --- | --- | --- |
| `method` | `string` |   |
| `path` | `string` |   |
| `query` optional | `Record<string, string \| number \| boolean \| undefined>` |   |
| `json` optional | `unknown` |   |
| `body` optional | `Uint8Array` |   |
| `contentType` optional | `string` |   |
| `accept` optional | `string` |   |
| `timeoutMs` optional | `number` |   |
| `raw` optional | `boolean` | Return the response unread (streams); errors are still thrown. |
| `region` optional | `Region` |   |
| `signal` optional | `AbortSignal` |   |

### RunEnd

How a run ended, as its log stream's done event says (`exitCode` once it ended).

| Field | Type | Description |
| --- | --- | --- |
| `runId` | `string` |   |
| `status` optional | `string` |   |
| `exitCode` optional | `number` |   |
| `oomKilled` | `boolean` |   |
| `timedOut` | `boolean` |   |
| `raw` | `Raw` |   |

### RunOptions

| Field | Type | Description |
| --- | --- | --- |
| `env` optional | `Record<string, string>` |   |
| `workdir` optional | `string` | /workspace (default) or a directory below it. |
| `timeoutSeconds` optional | `number` | Seconds the command may run (default 60). |
| `stdin` optional | `Uint8Array \| string` | Bytes piped to standard input. |
| `onStdout` optional | `(data: string) => void` | Called with live output, in order, as the server releases it. |
| `onStderr` optional | `(data: string) => void` |   |

### RunResult

| Field | Type | Description |
| --- | --- | --- |
| `runId` | `string` |   |
| `exitCode` | `number` |   |
| `stdout` | `string` |   |
| `stderr` | `string` |   |
| `durationMs` | `number` |   |
| `oomKilled` | `boolean` |   |
| `timedOut` | `boolean` |   |
| `streamed` | `boolean` | True when the output callbacks received live output; false when they got the final output at the end. |

### SSHCertificate

| Field | Type | Description |
| --- | --- | --- |
| `certificate` | `string` |   |
| `serial` | `string` |   |
| `keyId` | `string` |   |
| `principals` | `string[]` |   |
| `validAfter` optional | `Date` |   |
| `validBefore` optional | `Date` |   |
| `ssh` | `Raw` |   |

### Sandbox

| Field | Type | Description |
| --- | --- | --- |
| `id` | `string` |   |
| `status` | `string` |   |
| `name` optional | `string` |   |
| `templateId` optional | `string` |   |
| `cpuCount` optional | `number` |   |
| `memoryMb` optional | `number` |   |
| `timeoutSeconds` optional | `number` |   |
| `labels` optional | `Record<string, string>` |   |
| `statusReason` optional | `string` |   |
| `createdAt` optional | `Date` |   |
| `startedAt` optional | `Date` |   |
| `terminatedAt` optional | `Date` |   |
| `suspend` optional | `{ canPause: boolean; canResume: boolean; reason?: string }` | Whether pause and resume are possible now, as the server says. |
| `raw` | `Record<string, unknown>` | The server's full answer. |

### Snapshot

| Field | Type | Description |
| --- | --- | --- |
| `id` | `string` |   |
| `instanceId` | `string` |   |
| `status` | `'creating' \| 'ready' \| 'failed' \| string` |   |
| `label` | `string` |   |
| `sizeBytes` | `number` |   |
| `sha256` optional | `string` |   |
| `createdAt` optional | `Date` |   |
| `expiresAt` optional | `Date` |   |
| `failure` optional | `string` |   |
| `raw` | `Record<string, unknown>` |   |

### StartLeaseOptions

| Field | Type | Description |
| --- | --- | --- |
| `size` optional | `string` | A size the pool offers (default: the pool's). |
| `ttlSeconds` optional | `number` |   |
| `purpose` optional | `string` |   |
| `repo` optional | `string` |   |

### VaultEnvRef

One Vault value of a sandbox's environment: variable `name` gets `field` of the secret at `path`.

| Field | Type | Description |
| --- | --- | --- |
| `name` | `string` |   |
| `path` | `string` |   |
| `field` | `string` |   |

### Workspace

| Field | Type | Description |
| --- | --- | --- |
| `id` | `string` |   |
| `name` | `string` |   |
| `status` | `string` |   |
| `health` optional | `string` |   |
| `templateId` optional | `string` |   |
| `ownerId` optional | `string` |   |
| `projectId` optional | `string` |   |
| `createdAt` optional | `Date` |   |
| `updatedAt` optional | `Date` |   |
| `lastUsedAt` optional | `Date` |   |
| `raw` | `Raw` |   |

### WorkspaceBuild

A workspace build: start and stop are builds the server queues (202 Accepted).

| Field | Type | Description |
| --- | --- | --- |
| `id` | `string` |   |
| `workspaceId` | `string` |   |
| `state` | `string` |   |
| `desiredState` optional | `string` |   |
| `buildNumber` optional | `number` |   |
| `reason` optional | `string` |   |
| `failureMessage` optional | `string` |   |
| `createdAt` optional | `Date` |   |
| `completedAt` optional | `Date` |   |
| `raw` | `Raw` |   |

This page is generated from the SDK source (sdk/ts/sandscale). Do not edit it by hand.

---
Source: https://sandscale.dev/docs/sdks/typescript
