# SDKs

> The Sandscale SDKs for TypeScript and Python: install, authenticate, pick a region, start a sandbox and run a command, handle errors and retries.

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:

```sh
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

```ts
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 });
```

```python
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](https://sandscale.dev/docs/api/authentication). |
| `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](https://sandscale.dev/docs/concepts/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](https://sandscale.dev/docs/api/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](https://sandscale.dev/docs/sdks/typescript) · [Python](https://sandscale.dev/docs/sdks/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](https://sandscale.dev/docs/reference/api) for those.
- The Python SDK is synchronous; an asyncio client is planned.

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