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.