TypeScript SDK
@sandscale/sdk 0.2.0. Every method and option, generated from the SDK source.
SDK overview · Errors · Regions
Client
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.