SDKs

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.

FieldTypeDescription
region optionalRegionThe region to send this call to; overrides the client's region.
signal optionalAbortSignalAborts the call.

ClientOptions

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

ConnectInfo

FieldTypeDescription
sshHoststring
sshCommand optionalstring
portForwardCommand optionalstring
folder optionalstring
sshReadyboolean
sshUnavailableReason optionalstring
sshNote optionalstring
links{ ide: string; kind: string; url: string; requires?: string[] }[]
rawRaw

CreateSandboxOptions

FieldTypeDescription
template optionalstringA template id of the organization, or a built-in ("builtin:base", "builtin:python", ...).
snapshotId optionalstringStart from a snapshot instead.
cpuCount optionalnumberSize; with a template, nonzero values must match it (the server checks).
memoryMb optionalnumber
diskMb optionalnumber
timeoutSeconds optionalnumberSeconds until the sandbox stops (server default 3600, at most 86400).
env optionalRecord<string, string>Plain environment variables.
vaultEnv optionalVaultEnvRef[]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 optionalstring[]
name optionalstring
labels optionalRecord<string, string>
metadata optionalRecord<string, string>`metadata.project_id` runs the sandbox in a project.

ErrorExtra

FieldTypeDescription
requestId optionalstring
details optionalunknown
region optionalstring
retryAfterMs optionalnumber

FileEntry

FieldTypeDescription
pathstring
namestring
isDirboolean
size optionalnumber

Lease

FieldTypeDescription
idstring
poolIdstring
statestring
size optional{ name: string; cpuCores: number; memoryGb: number }
purpose optionalstring
repo optionalstring
workspaceId optionalstringThe lease's host is this cloud workspace (cloud and BYOC pools).
labHostId optionalstringThe lease's host is this lab host.
host optional{ status: string; ready: boolean; sshUser?: string }
createdAt optionalDate
expiresAt optionalDate
endedAt optionalDate
endReason optionalstring
rawRaw

LeaseConnectInfo

FieldTypeDescription
leaseLease
kind'workspace' | 'lab' | 'pending'`workspace`: connect like a workspace; `lab`: SSH through the lease's relay WebSocket.
workspace optionalConnectInfo
sshRelayPath optionalstringFor a lab lease: the relay path (WebSocket, binary SSH) on the region's API origin.
sshUser optionalstring

ListResult

FieldTypeDescription
dataT[]
pagesRegionPage[]

ListSandboxesOptions

FieldTypeDescription
status optionalstring
projectId optionalstring
limit optionalnumber
cursor optionalstringA cursor of one region's page; needs `region`.

ListWorkspacesOptions

FieldTypeDescription
limit optionalnumber
cursor optionalstring
all optionalbooleanInclude deleted workspaces.

OutputChunk

FieldTypeDescription
streamOutputStream
datastring
chunkIndexnumber

Pool

FieldTypeDescription
idstring
namestring
backendstring
sizes{ name: string; cpuCores: number; memoryGb: number }[]
defaultSize optionalstring
requiresApprovalboolean
rawRaw

RegionPage

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

FieldTypeDescription
region optionalRegion
nextCursor optionalstring
hasMoreboolean
error optionalSandscaleErrorSet 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.

FieldTypeDescription
region optionalRegionThe region the call went to (undefined: the client's base URL, no region named).

RequestSpec

FieldTypeDescription
methodstring
pathstring
query optionalRecord<string, string | number | boolean | undefined>
json optionalunknown
body optionalUint8Array
contentType optionalstring
accept optionalstring
timeoutMs optionalnumber
raw optionalbooleanReturn the response unread (streams); errors are still thrown.
region optionalRegion
signal optionalAbortSignal

RunEnd

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

FieldTypeDescription
runIdstring
status optionalstring
exitCode optionalnumber
oomKilledboolean
timedOutboolean
rawRaw

RunOptions

FieldTypeDescription
env optionalRecord<string, string>
workdir optionalstring/workspace (default) or a directory below it.
timeoutSeconds optionalnumberSeconds the command may run (default 60).
stdin optionalUint8Array | stringBytes piped to standard input.
onStdout optional(data: string) => voidCalled with live output, in order, as the server releases it.
onStderr optional(data: string) => void

RunResult

FieldTypeDescription
runIdstring
exitCodenumber
stdoutstring
stderrstring
durationMsnumber
oomKilledboolean
timedOutboolean
streamedbooleanTrue when the output callbacks received live output; false when they got the final output at the end.

SSHCertificate

FieldTypeDescription
certificatestring
serialstring
keyIdstring
principalsstring[]
validAfter optionalDate
validBefore optionalDate
sshRaw

Sandbox

FieldTypeDescription
idstring
statusstring
name optionalstring
templateId optionalstring
cpuCount optionalnumber
memoryMb optionalnumber
timeoutSeconds optionalnumber
labels optionalRecord<string, string>
statusReason optionalstring
createdAt optionalDate
startedAt optionalDate
terminatedAt optionalDate
suspend optional{ canPause: boolean; canResume: boolean; reason?: string }Whether pause and resume are possible now, as the server says.
rawRecord<string, unknown>The server's full answer.

Snapshot

FieldTypeDescription
idstring
instanceIdstring
status'creating' | 'ready' | 'failed' | string
labelstring
sizeBytesnumber
sha256 optionalstring
createdAt optionalDate
expiresAt optionalDate
failure optionalstring
rawRecord<string, unknown>

StartLeaseOptions

FieldTypeDescription
size optionalstringA size the pool offers (default: the pool's).
ttlSeconds optionalnumber
purpose optionalstring
repo optionalstring

VaultEnvRef

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

FieldTypeDescription
namestring
pathstring
fieldstring

Workspace

FieldTypeDescription
idstring
namestring
statusstring
health optionalstring
templateId optionalstring
ownerId optionalstring
projectId optionalstring
createdAt optionalDate
updatedAt optionalDate
lastUsedAt optionalDate
rawRaw

WorkspaceBuild

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

FieldTypeDescription
idstring
workspaceIdstring
statestring
desiredState optionalstring
buildNumber optionalnumber
reason optionalstring
failureMessage optionalstring
createdAt optionalDate
completedAt optionalDate
rawRaw

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