SDK quick start - InstaBox

This page walks through the calls an app needs: create a machine, run a command in it, pause and resume it, and delete it, then open a shell and the desktop and read usage. Everything runs on your server with an API key (ibk_...).

Never send the API key to a browser.

Install and authenticate

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

The SDK reads INSTABOX_API_KEY and INSTABOX_API_URL, or takes { apiKey, apiUrl } as options for a key from your own secret store. Without a key, every call throws InstaboxAuthError (missing_api_key) before sending a request. Over HTTP, send the key as X-API-Key or Authorization: Bearer.

Running the examples

The examples use import and top-level await. Save one as a .mjs file and run it with Node.js 18 or later, or set "type": "module" in your package.json for a .js file.So that a failed step does not leave a machine running, wrap the steps after create in try and finally { await sbx.kill() }. Your app keeps the machine and deletes it when your user is done.

Create a machine

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

const sbx = await Sandbox.create('agent-browser', {  // a template, a snapshot name, or a snapshot ID
  metadata: { customer: 'acme' },                    // your own tags, to find it later
  vault: false,                                      // no personal Vault delivery
})
console.log(sbx.sandboxId)                           // m_...: store it with your user

H="X-API-Key: $INSTABOX_API_KEY"
curl -s -H "$H" -H "Idempotency-Key: $(uuidgen)" -H 'Content-Type: application/json' \
  -d '{"name": "box", "templateId": "agent-browser"}' "$INSTABOX_API_URL/v1/machines"
curl -s -H "$H" "$INSTABOX_API_URL/v1/operations/op_...?wait=25s"  # long poll, until "state": "succeeded"

Sandbox.create waits until the machine runs, so the script prints the new machine’s ID, m_.... agent-browser is the default template: Linux, a desktop, and a browser. Later, from another request:

const sbx = await Sandbox.connect(sandboxId)                 // attach by ID; resumes it
await Sandbox.list({ metadata: { customer: 'acme' } })     // find machines by tag

Over HTTP, lifecycle calls (create, pause, resume, delete) return an operation. Poll it until succeeded or failed before the next change to that machine. Lifecycle calls need an Idempotency-Key header and answer 400 without one. Reuse a key only to retry the same request.

Create over HTTP: defaults and refusals

POST /v1/machines takes {}, which creates an agent-browser machine named box- and 8 random hex digits. An unknown templateId is 400, listing the templates your plan can create from. A body field the API lacks is 400 unknown_field. For "template", the error asks: did you mean "templateId"?

Run a command and move files

const r = await sbx.commands.run('python3 -c "print(6 * 7)"', {
  cwd: '/data/home',
  timeoutMs: 60_000,
})
console.log(r.stdout, r.exitCode)   // a non-zero exit throws CommandExitError (stdout, stderr, exitCode)

await sbx.files.write('/data/home/app.py', 'print("hi")')
console.log(await sbx.files.read('/data/home/app.py'))

curl -s -H "$H" -H 'Content-Type: application/json' \
  -d '{"cmd": "uname -a", "timeoutSeconds": 60}' "$INSTABOX_API_URL/v1/machines/m_.../exec"
curl -s -H "$H" -H 'Content-Type: application/json' \
  -d '{"argv": ["printf", "%s|", "a b", "$X"]}' "$INSTABOX_API_URL/v1/machines/m_.../exec"  # no shell: prints a b|$X|

The TypeScript prints the command’s output, 42, and its exit code, 0. Then it prints the file it wrote, print("hi"). To run a command without throwing on a non-zero exit, use sbx.commands.exec.

exec over HTTP

Send cmd (a shell string, run with bash -lc) or argv (a program and its arguments, run with no shell), not both.
It returns stdout, stderr, and exitCode when the command exits. After timeoutSeconds (60 by default, at most 600), the command is killed.
With Accept: text/event-stream (instabox exec --stream), it streams output as the command runs. To run a longer job detached, use instabox exec --background and instabox jobs.
It takes no Idempotency-Key, so a retry runs the command again.
When a disk of the machine is at least 90% full, or the command failed with No space left on device, the result carries a diskWarning. Its fields are mount, usedPct, level, noSpace, and message, and it names the full disk and the fix: instabox resize <box> --disk <GiB> grows /data, live on a running machine. instabox exec prints it on stderr.

Pause and resume the machine

await sbx.pause()                     // memory, files and running processes are kept
await sbx.resume()                    // carries on where it left off, usually in about a second

const peek = await Sandbox.connect(sbx.sandboxId, { resume: false })  // look without waking it
console.log((await peek.getInfo()).state)
const again = await Sandbox.connect(sbx.sandboxId)                   // connect also resumes it
console.log(await again.isRunning())

curl -s -X POST -H "$H" -H "Idempotency-Key: $(uuidgen)" "$INSTABOX_API_URL/v1/machines/m_.../suspend"
curl -s -X POST -H "$H" -H "Idempotency-Key: $(uuidgen)" "$INSTABOX_API_URL/v1/machines/m_.../resume"

The first log shows the machine’s state without waking it. The second prints true, because connect resumes the machine. Idle machines pause by themselves after minutes. To change that, call sbx.setAutoSuspend(idleMs). sbx.stop() shuts the machine down and keeps /data. See Lifecycle.

Delete the machine

const id = sbx.sandboxId
console.log(await sbx.kill())           // deletes the machine and its disks; false if already gone
console.log(await Sandbox.kill(id))     // the same, by ID from any later request

curl -s -X DELETE -H "$H" -H "Idempotency-Key: $(uuidgen)" -H "X-Confirm-Delete: m_..." \
  "$INSTABOX_API_URL/v1/machines/m_..."

The first log prints true. The second prints false, because the machine is already gone.

Open an SSH session

sbx.sshCredentials(publicKey) takes your public key and returns a short-lived certificate. Over HTTP, send your public key to POST /v1/machines/{id}/connections, with an Idempotency-Key. It returns the certificate and the host CA. See SSH.

Full example

The example prints the ssh command to run.

import { execFileSync } from 'node:child_process'
import { existsSync, mkdtempSync, readFileSync } from 'node:fs'
import { homedir, tmpdir } from 'node:os'
import { join } from 'node:path'
import { Sandbox } from '@insforge/instabox-sdk'

// your key pair; a throwaway one if you have none
let key = join(homedir(), '.ssh', 'id_ed25519')
if (!existsSync(`${key}.pub`)) {
  key = join(mkdtempSync(join(tmpdir(), 'instabox-ssh-')), 'id_ed25519')
  execFileSync('ssh-keygen', ['-q', '-t', 'ed25519', '-N', '', '-f', key])
}
const publicKey = readFileSync(`${key}.pub`, 'utf8')
const sbx = await Sandbox.create('agent-browser', { vault: false })
try {
  const ssh = await sbx.sshCredentials(publicKey, { ttlSeconds: 3600 })
  // save ssh.certificate as <key>-cert.pub next to the private key,
  // add ssh.knownHostsLine to known_hosts, then:
  console.log(`ssh -i ${key} -p ${ssh.port} ${ssh.username}@${ssh.host}`)
} finally {
  // your app keeps the machine while the session lasts
  await sbx.kill()
}

Drive the desktop

await sbx.desktop.start()                     // safe to call again
console.log(await sbx.desktop.status())       // { installed, running, width, height }
await sbx.desktop.open('https://example.com')
const png = await sbx.desktop.screenshot()
await sbx.desktop.click(640, 400)
await sbx.desktop.type('hello')
await sbx.desktop.press('Enter')

Any key with machines:write that can reach the machine, including a workspace key, opens its desktop over GET /v1/machines/{id}/vnc. That route is a WebSocket carrying the VNC (RFB) stream. A share link (sbx.desktop.streamUrl()) is for the machine’s creator only. See Desktop for links, embedding, and an agent loop.

Open the VNC WebSocket from Node.js

import { randomBytes } from 'node:crypto'
import http from 'node:http'
import https from 'node:https'

const api = new URL(process.env.INSTABOX_API_URL ?? 'https://api.instabox.sh')
const status = await new Promise((ok, fail) => {
  const req = (api.protocol === 'https:' ? https : http).request(
    new URL(`/v1/machines/${sbx.sandboxId}/vnc`, api),
    {
      headers: {
        'X-API-Key': process.env.INSTABOX_API_KEY,
        Connection: 'Upgrade',
        Upgrade: 'websocket',
        'Sec-WebSocket-Version': '13',
        'Sec-WebSocket-Key': randomBytes(16).toString('base64'),
      },
    },
  )
  // 101: hand the socket to your VNC client; this example closes it
  req.on('upgrade', (res, socket) => {
    socket.destroy()
    ok(res.statusCode)
  })
  req.on('response', (res) => fail(new Error(`vnc: HTTP ${res.statusCode}`)))
  req.on('error', fail)
  req.end()
})
console.log(status)

Read usage and metrics per customer

Tag each machine with your customer when you create it, then read usage by that tag:

const machines = await Sandbox.list({ metadata: { customer: 'acme' } })
let seconds = 0
for (const m of machines) {
  const u = await Sandbox.getUsage(m.sandboxId)        // running seconds this UTC month
  seconds += u.runningSeconds
  const samples = await Sandbox.getMetrics(m.sandboxId) // CPU and memory, one sample per 30 s, oldest first
  console.log(m.sandboxId, samples.at(-1)?.cpuUsedPct)
}
console.log(machines.length, seconds)

The script prints each machine’s latest CPU use, then the number of machines and their total running seconds. getUsage covers the current UTC month by default and counts running time only, not paused or stopped time. A Sandbox object has the same calls: sbx.getUsage() and sbx.getMetrics(). Sandbox.usage() returns account counts, storage, and limits.

Handle errors

Calls throw InstaboxError with status and code, such as not_found or quota_exceeded. A missing or bad key throws InstaboxAuthError. See Errors.

Use the CLI with a key

With INSTABOX_API_KEY set, the CLI needs no login:

npm install -g instabox
instabox create --name box --template agent-browser
instabox exec box -- uname -a
instabox exec --background box -- 'npm run build'   # detached job: prints its ID
instabox jobs logs box <job> -f                     # follow it; exits with its code
instabox agent prompt box --provider codex -f 'fix the failing test'   # a coding agent turn, its JSONL events
instabox agent steer box 'use the existing helper instead'             # interrupt it and follow up
instabox ssh box
instabox rm --yes box
instabox run -- uname -a        # one-shot: create, run, delete
instabox run --push . -- ls     # upload this directory (git-ignored files skipped) first

Reference

SDK calls and their HTTP endpoints

SDK	HTTP
`Sandbox.create`	`POST /v1/machines`
`pause`, `resume`	`POST /v1/machines/{id}/suspend`, `.../resume`
`kill`	`DELETE /v1/machines/{id}`
`commands.run`	`POST /v1/machines/{id}/exec`
`sshCredentials`	`POST /v1/machines/{id}/connections`
`desktop.start`	`POST /v1/machines/{id}/desktop`
`desktop.streamUrl`, `revokeStreamUrls`	`POST` and `DELETE /v1/machines/{id}/desktop/stream` (creator only)
your VNC viewer	`GET /v1/machines/{id}/vnc` (WebSocket, any key with `machines:write`, a workspace key too)
`getMetrics`	`GET /v1/machines/{id}/metrics`
`getUsage`	`GET /v1/machines/{id}/usage`
`Sandbox.usage`	`GET /v1/usage`

SDK reference

Every call, by task: snapshots, labels, files and more.

API reference

Every endpoint an API key calls.

Python SDK

The same calls from Python: pip install instabox-sdk.

​Install and authenticate

​Create a machine

​Run a command and move files

​Pause and resume the machine

​Delete the machine

​Open an SSH session

​Drive the desktop

​Read usage and metrics per customer

​Handle errors

​Use the CLI with a key

​Reference

SDK reference

API reference

Python SDK

Install and authenticate

Create a machine

Run a command and move files

Pause and resume the machine

Delete the machine

Open an SSH session

Drive the desktop

Read usage and metrics per customer

Handle errors

Use the CLI with a key

Reference