TypeScript SDK

Install, authentication, errors and types of @insforge/instabox-sdk, version 0.7.0. A Sandbox is one machine: its methods are on the Sandbox, Commands, Files, Desktop and Metrics and usage pages. The common calls, step by step, are in the SDK quickstart.

import { Sandbox } from '@insforge/instabox-sdk'

const sbx = await Sandbox.create('agent-browser')
const r = await sbx.commands.run('uname -a')
console.log(r.stdout)
await sbx.kill()

Install and authenticate

npm install @insforge/instabox-sdk
export INSTABOX_API_KEY=ibk_...
# optional, the default is https://api.instabox.sh
export INSTABOX_API_URL=https://api.instabox.sh

Every static call (create, connect, list, kill, the snapshot calls and the metrics and usage calls) also takes the key and URL as options, which win over the environment. A Sandbox object keeps its connection, so its own methods take no key.

const sbx = await Sandbox.create('agent-browser', {
  apiKey: process.env.INSTABOX_API_KEY,
  apiUrl: 'https://api.instabox.sh',
})

With no key from either, the call throws InstaboxAuthError with code missing_api_key (status 0) before any request. The key is sent as the X-API-Key header.

ConnectionOptions

These apply to every static call.

Option	Type	Default
`apiKey`	`string`	env `INSTABOX_API_KEY`
`apiUrl`	`string`	env `INSTABOX_API_URL`, else `https://api.instabox.sh`
`requestTimeoutMs`	`number`	60 000 per HTTP request. A command gets its own timeout plus 30 000
`operationTimeoutMs`	`number`	600 000: the wait for create, pause, resume and kill
`fetch`	`typeof fetch`	the global `fetch` (Node 18+, Bun, Deno)
`pollIntervalMs`	`number`	250: first delay of operation polling, grows 1.5x to 1 s
`retryDelayMs`	`number`	250: first delay between retries

Scopes

The API key scopes each call needs.

Scope	Allows
`machines:read`	`Sandbox.list`, `getInfo`, `isRunning`, `getMetrics`, `getUsage`, `Sandbox.usage`
`machines:write`	`create`, `connect` (resume), `pause`, `resume`, `stop`, `setAutoSuspend`, `setMetadata`, `commands`, `files`, `sshCredentials`
`machines:delete`	`kill`
`images:read`	Resolve private snapshot names, `listSnapshots`, `getSnapshot`
`images:write`	`createSnapshot`
`images:delete`	`deleteSnapshot`

:write and :delete include :read. Creating from a snapshot name also needs images:read. A call outside the key’s scopes throws InstaboxAuthError (403 missing_scope).

Errors

Class	When
`InstaboxError`	Base class of every error. Fields: `status`, `code`, `message`, `requestId`, `retryable`, `operationId`
`InstaboxAuthError`	401 or 403: a bad or revoked key, or a missing scope. No key at all: `missing_api_key`, status 0
`InstaboxQuotaError`	429, such as `quota_exceeded`
`InstaboxTimeoutError`	A request or an operation did not finish in time
`CommandExitError`	A command exited non-zero. Also has `stdout`, `stderr`, `exitCode`, `timedOut`, `truncated`, `error`

status is 0 for errors that did not come from an HTTP response. A failed operation (for example no_capacity while creating) throws InstaboxError with the operation’s code and operationId.

Code	Meaning
`missing_api_key`	No key in the options or the environment
`missing_scope`	The key lacks a scope the call needs (403). Older servers send `insufficient_scope`
`missing_key`, `malformed_key`, `invalid_key`, `expired_key`, `revoked_key`	The key was not sent, is not a key, does not exist, expired or was revoked (401)
`not_found`	No such machine or snapshot
`operation_conflict`	Another operation runs on the machine (409). `operationId` names it
`quota_exceeded`	An account limit was reached (429)
`spec_not_allowed`	A size your plan does not offer, a disk size at create, or growing a free machine’s disks (400). Another idle time on the free plan (403)
`template_not_allowed`	A template your plan does not offer: the free plan creates from only (403)
`is_a_directory`	`files.write` to a directory
`source_error`	The stream given to `files.write` threw. The original error is the `cause`, and the file keeps its old content
`local_not_found`	`files.upload`: the local directory does not exist
`local_io_error`	`files.upload` or `files.download`: reading or writing the local disk failed
`not_a_directory`	`files.upload` or `files.download`: a file where a directory was expected
`transfer_failed`	`files.upload` or `files.download`: `tar` failed in the machine (`permission_denied`, 403, when it was refused access)
`unsupported`	`files.upload` or `files.download` in a browser or a Worker, which have no local file system
`request_timeout`, `operation_timeout`	A request or an operation took too long
`network_error`	The request did not reach the API

Reads, and changes (which carry an Idempotency-Key), are retried up to 3 times with backoff on 502, 503, 504 and network errors. Every server code: Errors.

Types

Type	What
`ConnectionOptions`	`apiKey`, `apiUrl` and the timeouts every static call takes
`SandboxOpts`, `SandboxConnectOpts`, `SandboxListOpts`	Options of `create`, `connect`, `list`
`SandboxInfo`	What `getInfo` and `list` return
`Machine`, `MachineSpec`, `MachineState`	The raw machine from the API, its size, its state
`CreateSnapshotOpts`, `Snapshot`	Snapshot options, a saved snapshot
`SandboxMetrics`, `SandboxMetricsOpts`	`getMetrics` samples and options
`SandboxUsage`, `SandboxUsageOpts`	`getUsage` result and options
`Usage`, `UsageLimits`, `UsageStorage`, `UsageMachineStorage`	What `Sandbox.usage` returns
`SshCredentials`	What `sshCredentials` returns
`CommandOptions`, `CommandResult`, `CommandHandle`, `CommandWaitOptions`	`commands.run` options and results, `CommandHandle.wait` options
`EntryInfo`, `WriteInfo`	`files.list` entries, `files.write` result
`WriteData`, `WriteOptions`	What `files.write` takes: a string, bytes or a stream. `signal`
`FileStream`, `ReadStreamOptions`	What `files.readStream` returns, and its `signal`
`UploadOptions`, `UploadInfo`	`files.upload` options (`git`, `all`, `signal`) and result
`DownloadOptions`, `DownloadInfo`	`files.download` options (`signal`) and result
`DesktopStatus`, `DesktopStream`	`desktop.status` and `desktop.streamUrl` results
`MouseButton`	`'left'`, `'right'`, `'middle'`
`ScrollDirection`	`'up'`, `'down'`, `'left'`, `'right'`
`Template`, `TemplateRef`, `Operation`, `ApiError`	API objects

Constants

Constant	Value
`DEFAULT_API_URL`	`https://api.instabox.sh`
`DEFAULT_TEMPLATE`	`agent-browser`
`FALLBACK_TEMPLATE`	`universal`
`MAX_FILE_BYTES`	10 MiB, the default cap of `files.read`
`MAX_UPLOAD_BYTES`	5 GiB, the largest file `files.write` sends
`MAX_STDIN_BYTES`	1 MiB, the most stdin sent in the request itself
`DESKTOP_DISPLAY`	`:1`

Get started

TypeScript

Python

Install and authenticate

ConnectionOptions

Scopes

Errors

Types

Constants

​Install and authenticate

​ConnectionOptions

​Scopes

​Errors

​Types

​Constants

Install and authenticate

ConnectionOptions

Scopes

Errors

Types

Constants