SDKs

SDKs

Official SDKs for TypeScript and Python. They send your request as you and hand back the server's answer, so every limit and permission is the server's.

Install

The TypeScript SDK is on npm:

npm install @sandscale/sdk

It needs Node.js 22 or later and has no runtime dependencies.

The Python SDK is coming soon: it is not on PyPI yet. When it is, it installs with pip install sandscale, needs Python 3.10 or later and depends only on httpx. The Python examples on this page show how it will work.

Start a sandbox and run a command

import { Sandscale } from '@sandscale/sdk';

const sandscale = new Sandscale({ apiKey: process.env.SANDSCALE_API_KEY });

const box = await sandscale.sandboxes.create({ template: 'builtin:python', timeoutSeconds: 600 });
const run = await sandscale.sandboxes.run(box.id, 'python -c "print(6*7)"', {
  region: box.region,
  onStdout: (text) => process.stdout.write(text),
});
console.log('exit code', run.exitCode);
await sandscale.sandboxes.stop(box.id, { region: box.region });
import sys
from sandscale import Sandscale

with Sandscale() as sandscale:  # reads SANDSCALE_API_KEY
    box = sandscale.sandboxes.create(template="builtin:python", timeout_seconds=600)
    try:
        run = sandscale.sandboxes.run(box.id, 'python -c "print(6*7)"', region=box.region, on_stdout=sys.stdout.write)
        print("exit code", run.exit_code)
    finally:
        sandscale.sandboxes.stop(box.id, region=box.region)

With an output callback, run starts the command and streams its output live; without one it waits and returns the exit code, output, duration and whether it ran out of memory or time.

Authenticate

TypeScript Python Environment What it is
apiKey api_key SANDSCALE_API_KEY A personal API key.
token token Your own sign-in access token, or a function that returns a current one.
orgId org_id SANDSCALE_ORG_ID Your organization ID. Workspace and build host calls need it.
baseUrl base_url SANDSCALE_BASE_URL Defaults to https://api.sandscale.dev.

Credentials stay in memory and are sent only to Sandscale’s API hosts. Redirects are never followed, so a credential never leaves with one.

Regions

Pass region ('us', and 'eu' when Europe opens; it is coming soon) to the client, as the default for every call, or to a single call. Without one, requests go to api.sandscale.dev, which routes to your region and defaults to the United States. Everything you read carries the region it came from; pass it back on later calls for that resource. A list without a region reads every live region and merges the results, and tells you per region if one did not answer. See Regions.

Errors

Every API error raises a SandscaleError with the server’s status, code, message and request ID. Catch a family with its subclass:

Error When
InvalidRequestError 400, 413, 422
AuthenticationError 401
PermissionDeniedError 403
NotFoundError 404
ConflictError 409, for example a paused or ended sandbox
LimitExceededError 402, or a quota or limit code such as quota_exceeded
RateLimitError 429, with the time to wait
EntitlementError Your plan does not include it, or payment is required
RegionError A credential from another region (wrong_region)
KillSwitchError Your organization’s kill switch is on
ServerError 5xx

A failed connection raises ConnectionError in TypeScript and APIConnectionError in Python. See Errors for what each code means.

Retries

Only reads (GET) are retried: up to twice by default (maxRetries or max_retries), after a connection error, 429, 502, 503 or 504, with exponential backoff and jitter, or after the server’s Retry-After. Calls that change something are sent once. Kill switch, plan and region refusals are never retried.

Reference

Every method and option, generated from the SDK source: TypeScript · Python.

Known gaps

  • Sandboxes, workspaces and build hosts are covered. Object storage, Vault and Agent Cloud are not in the SDKs yet; use the API for those.
  • The Python SDK is synchronous; an asyncio client is planned.