### sbx.desktop.start

Source: https://instabox.sh/docs/sdk

Starts the desktop environment. Resolves once the desktop runs, leaving a running one as is. On templates without the desktop, it installs it first (about half a minute, once).

```APIDOC
## sbx.desktop.start

### Description
Starts the desktop environment. Resolves once the desktop runs, leaving a running one as is. On templates without the desktop, it installs it first (about half a minute, once).

### Method
start

### Signature
start(opts?: { width?: number; height?: number }): Promise<DesktopStatus>

### Parameters
- **opts.width** (number) - Optional - Screen width in pixels. Range: 800 to 2560. Default: 1280.
- **opts.height** (number) - Optional - Screen height in pixels. Range: 600 to 1600. Default: 800.

### Returns
- Promise<DesktopStatus> - The desktop status, including `installed`, `running`, and `width` and `height` while running.

### Notes
- The desktop runs on X display `:1` (DESKTOP_DISPLAY).
```

--------------------------------

### port setup

Source: https://instabox.sh/docs/cli

Installs the instabox-port command in the machine.

```APIDOC
## port setup

### Description
Installs the instabox-port command in the machine.

### Syntax
```
port setup <id-or-name>
```

### Parameters
- **id-or-name** (string) - Required - The machine identifier or name.

```

--------------------------------

### One-command setup with npx instabox@latest sh

Source: https://instabox.sh/docs/start

Run this command to sign in through the browser, start a new machine, install the instabox CLI and agent skills, and open a shell over SSH.

```bash
npx instabox@latest sh
```

--------------------------------

### Example: Get Metrics and Usage

Source: https://instabox.sh/docs/sdk

Example showing how to get the last 15 minutes of CPU and memory metrics, and usage since the start of October (UTC). Logs runningSeconds and vcpuSeconds.

```typescript
// the last 15 minutes of CPU and memory
const samples = await sbx.getMetrics({
  since: new Date(Date.now() - 15 * 60_000),
})
// what it used since the start of October (UTC)
const usage = await Sandbox.getUsage(sbx.sandboxId, {
  from: new Date('2026-10-01T00:00:00Z'),
})
console.log(usage.runningSeconds, usage.vcpuSeconds)
```

--------------------------------

### SDK: Start desktop and perform actions

Source: https://instabox.sh/docs/desktop

Initializes an agent-browser sandbox, starts the desktop, and demonstrates core actions: open a URL, take a screenshot, click, press keys, type text, and scroll. `start()` is safe to call again and leaves a running desktop alone.

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

const sbx = await Sandbox.create('agent-browser')
await sbx.desktop.start({ width: 1280, height: 800 })

await sbx.desktop.open('https://example.com')        // opens the browser
const png = await sbx.desktop.screenshot()           // PNG bytes, e.g. for a vision model
await sbx.desktop.click(640, 400)                    // { button: 'right' }, { double: true }
await sbx.desktop.press(['ctrl', 'l'])               // a key or a chord
await sbx.desktop.type('instabox.sh')                // any text, quotes and unicode included
await sbx.desktop.press('Enter')
await sbx.desktop.scroll({ direction: 'down', amount: 5 })
```

--------------------------------

### GET /v1/templates

Source: https://instabox.sh/docs/api/account

Lists the templates that a machine can start from, including the software each one has.

```APIDOC
## GET /v1/templates

### Description
Lists the templates that a machine can start from, including the software each one has.

### Method
GET

### Endpoint
/v1/templates

### Request Example
curl https://api.instabox.sh/v1/templates -H "X-API-Key: $INSTABOX_API_KEY"

### Response
#### Success Response (200)
- **templates** (array) - List of templates.
  - **id** (string) - Template identifier.
  - **version** (string) - Template version.
  - **description** (string) - Description of the template.
  - **arch** (string) - Architecture (e.g., x86_64).
  - **defaultSpec** (object) - Default specification with vcpus, memMiB, persistentDiskGiB.

#### Response Example
{
  "templates": [
    {
      "id": "universal",
      "version": "2026-10-13.10",
      "description": "dev plus Docker, Python (uv), Go and Rust",
      "arch": "x86_64",
      "defaultSpec": { "vcpus": 4, "memMiB": 8192, "persistentDiskGiB": 20 },
      …
    }
  ]
}
```

--------------------------------

### HTTP: Start desktop

Source: https://instabox.sh/docs/desktop

Starts the desktop session via HTTP API.

```APIDOC
## POST /v1/machines/{machine_id}/desktop

### Description
Starts the desktop session with specified dimensions.

### Method
POST

### Endpoint
`/v1/machines/{machine_id}/desktop`

### Parameters
#### Path Parameters
- **machine_id** (string) - Required - The machine ID.

#### Request Body
- **action** (string) - Required - Must be "start".
- **width** (number) - Required - Width of the desktop.
- **height** (number) - Required - Height of the desktop.

### Request Example
```json
{
  "action": "start",
  "width": 1280,
  "height": 800
}
```

### Response
No response body specified.
```

--------------------------------

### SDK: Start desktop

Source: https://instabox.sh/docs/desktop

Starts the desktop session with specified dimensions. Safe to call again; leaves a running desktop alone.

```APIDOC
## SDK: Start desktop

### Description
Starts the desktop session with specified width and height. Safe to call again; leaves a running desktop alone.

### Method
SDK Method

### Endpoint
`sbx.desktop.start({ width, height })`

### Parameters
- **width** (number) - Required - Width of the desktop in pixels.
- **height** (number) - Required - Height of the desktop in pixels.

### Request Example
```javascript
await sbx.desktop.start({ width: 1280, height: 800 })
```

### Response
No return value.
```

--------------------------------

### Start machine response (202 Accepted)

Source: https://instabox.sh/docs/api/lifecycle

Example JSON response for the start operation, showing the operation ID, machine ID, type, state, and timestamps.

```json
{
  "id": "op_7xk2mq4tz5rbw3vn6pd2hs4jye",
  "machineId": "m_agqteugyy5px6hzeadbh4ldjo4",
  "type": "start",
  "state": "queued",
  "error": null,
  "createdAt": "2026-10-13T09:12:04Z",
  "updatedAt": "2026-10-13T09:12:04Z"
}
```

--------------------------------

### Step-by-step installation and login

Source: https://instabox.sh/docs/start

Install the CLI, sign in through the browser, create a machine named 'dev' with the universal template, and SSH into it. On a computer without a browser, use `instabox login --device`.

```bash
curl -fsSL https://api.instabox.sh/install.sh | sh    # install the CLI
instabox login                             # sign in through the browser
instabox create --name dev --template universal
instabox ssh dev
```

--------------------------------

### Install CLI and use with API key

Source: https://instabox.sh/docs/keys-sdk

Installs the CLI and shows create, exec, ssh, and rm commands using the API key from the environment.

```bash
curl -fsSL https://api.instabox.sh/install.sh | sh
instabox create --name box --template herdr
instabox exec box -- uname -a
instabox ssh box
instabox rm box
```

--------------------------------

### Get a machine response (200 OK)

Source: https://instabox.sh/docs/api/machines

Example response for the get machine endpoint, showing full machine details.

```json
{
  "id": "m_agqteugyy5px6hzeadbh4ldjo4",
  "name": "dev",
  "state": "running",
  "desiredState": "running",
  "revision": 3,
  "operationId": null,
  "template": { "id": "universal", "version": "2026-10-13.10", "digest": "sha256:9f2c…" },
  "spec": { "vcpus": 4, "memMiB": 8192, "persistentDiskGiB": 20 },
  "storage": { "sizeGiB": 20, "mountPath": "/data", "persistent": true, "synced": true },
  "runtime": { "ready": true },
  "autoSuspendAfterSeconds": 1800,
  "metadata": { "task": "review" },
  "guestUser": "alice",
  "createdAt": "2026-10-13T09:12:04Z",
  "updatedAt": "2026-10-13T09:12:31Z"
}
```

--------------------------------

### Install mosh on snapshots made before mosh was added

Source: https://instabox.sh/docs/ssh

Install mosh on the machine itself for snapshots created before mosh was added. Run this once on the machine.

```bash
sudo apt install mosh
```

--------------------------------

### sbx.desktop.start()

Source: https://instabox.sh/docs/integrate

Starts the desktop. Safe to call again.

```APIDOC
## sbx.desktop.start()

### Description
Starts the desktop. Safe to call again.

### Method
start

### Parameters
None

### Request Example
```javascript
await sbx.desktop.start()
```

### Response
#### Success Response
No return value documented.
```

--------------------------------

### Get usage and limits - 200 OK response

Source: https://instabox.sh/docs/api/account

Example JSON response from /v1/usage showing current usage metrics and limits.

```json
{
  "machines": 2,
  "snapshots": 1,
  "storedBytes": 6442450944,
  "computedAt": "2026-10-13T10:00:00Z",
  "limits": { "maxMachines": 5, "maxSnapshots": 10, "maxStoredGiB": 200, … },
  …
}
```

--------------------------------

### Control the desktop with sbx.desktop

Source: https://instabox.sh/docs/integrate

Starts the desktop, creates a view-only stream URL, opens a URL, takes screenshots, simulates clicks and typing, and revokes stream URLs. Safe to call start() again. Revoking closes open viewers within seconds.

```javascript
// starts the desktop; safe to call again
await sbx.desktop.start()

// Let people watch it: a link to one machine's desktop,
// for a new tab or an <iframe>
const { url } = await sbx.desktop.streamUrl({
  viewOnly: true,
  ttlSeconds: 3600,
})

// Let an agent use it
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')

// Take the links away (e.g. when a user's access ends);
// open viewers close within seconds
await sbx.desktop.revokeStreamUrls()
```

--------------------------------

### Watch load and bill per machine

Source: https://instabox.sh/docs/integrate

Example of retrieving metrics and usage data for machines, demonstrating how to get CPU/memory samples and calculate billing seconds.

```APIDOC
## Watch load and bill per machine

### Description
Retrieve metrics and usage data for machines to monitor load and calculate billing.

### Code Example
```javascript
// CPU and memory, one sample per 30 s, oldest first
const samples = await sbx.getMetrics()
// bill a customer: running seconds of their machines this month
const machines = await Sandbox.list({ metadata: { customer: 'acme' } })
let seconds = 0
for (const m of machines) {
  const u = await Sandbox.getUsage(m.sandboxId)
  seconds += u.runningSeconds
}
```

### Notes
- `getUsage` covers the current UTC month by default and counts running time only, not paused or stopped.
- See Metrics and usage for every field.
```

--------------------------------

### Install TypeScript SDK

Source: https://instabox.sh/docs/keys-sdk

Installs the @insforge/instabox-sdk package via npm.

```bash
npm install @insforge/instabox-sdk
```

--------------------------------

### Copying a sandbox with snapshots

Source: https://instabox.sh/docs/sdk

Example showing how to save a snapshot and create a copy from it.

```APIDOC
## Copying a sandbox with snapshots

### Description
To copy a sandbox, save a snapshot and create from it. A copy uses its creation request's selections, not the source sandbox's grants. Omitting both Secret fields does not enroll the copy in Secrets. `vault: false` disables only Vault delivery. To explicitly select Secrets, use the CLI or HTTP API. Values previously copied into snapshot files remain; a new selection cannot remove them.

### Example
```javascript
const snap = await sbx.createSnapshot({ name: 'my-setup' })
const copy = await Sandbox.create(snap.id, { vault: false })
```
```

--------------------------------

### Publish and serve with instabox-port agent

Source: https://instabox.sh/docs/ports

Inside the machine, the `instabox-port` agent publishes a port or serves a folder with an index.html. `instabox port setup dev` installs the agent where it is missing.

```bash
instabox-port publish 3000 --name 'Web app'
instabox-port serve ./report --port 8080          # serve a folder with an index.html
```

--------------------------------

### HTTP: Start desktop, create stream, revoke stream

Source: https://instabox.sh/docs/desktop

Curl commands to start the desktop, create a stream URL, and revoke all streams. Both stream calls need a key with `machines:write`.

```bash
H="X-API-Key: $INSTABOX_API_KEY"
curl -s -H "$H" -H 'Content-Type: application/json' \
  -d '{"action": "start", "width": 1280, "height": 800}' "$INSTABOX_API_URL/v1/machines/m_.../desktop"
curl -s -H "$H" -H 'Content-Type: application/json' \
  -d '{"viewOnly": true, "ttlSeconds": 3600}' "$INSTABOX_API_URL/v1/machines/m_.../desktop/stream"   # {url, expiresAt}
curl -s -X DELETE -H "$H" "$INSTABOX_API_URL/v1/machines/m_.../desktop/stream"                     # revoke
```

--------------------------------

### Install SDK and set API key

Source: https://instabox.sh/docs/integrate

Install the SDK and set the INSTABOX_API_KEY environment variable. The SDK reads this variable automatically, making the apiKey option optional. Without a key, calls throw InstaboxAuthError (missing_api_key).

```bash
npm install @insforge/instabox-sdk
export INSTABOX_API_KEY=ibk_...
```

--------------------------------

### Get current user - 200 OK response

Source: https://instabox.sh/docs/api/account

Example JSON response from /v1/me showing user details such as userId, login, and admin flag.

```json
{ "userId": 42, "login": "octocat", "admin": false, … }
```

--------------------------------

### Response for file read

Source: https://instabox.sh/docs/api/commands

Example 200 OK response showing directory metadata and entries.

```json
{
  "path": "/data/home",
  "type": "dir",
  "size": 0,
  "mode": "drwxr-xr-x",
  "modTime": "2026-10-13T09:30:12Z",
  "entries": [
    { "name": "app", "type": "dir", "size": 0, "mode": "drwxr-xr-x", "modTime": "2026-10-13T09:28:40Z" },
    { "name": "notes.txt", "type": "file", "size": 5, "mode": "-rw-r--r--", "modTime": "2026-10-13T09:30:12Z" }
  ]
}
```

--------------------------------

### Running a background command with sbx.commands.run

Source: https://instabox.sh/docs/sdk

Example of starting a command in the background with background: true, which returns a CommandHandle. The handle provides a kill() method that sends SIGTERM to the process group.

```typescript
const server = await sbx.commands.run('node server.js', {
  background: true,
})
await server.kill()
```

--------------------------------

### Operation response example

Source: https://instabox.sh/docs/api/operations

Example 200 OK response for a successful create operation. Shows the operation object with id, machineId, type, state, error, and timestamps.

```json
{
  "id": "op_7xk2mq4tz5rbw3vn6pd2hs4jye",
  "machineId": "m_agqteugyy5px6hzeadbh4ldjo4",
  "type": "create",
  "state": "succeeded",
  "error": null,
  "createdAt": "2026-10-13T09:12:04Z",
  "updatedAt": "2026-10-13T09:12:04Z"
}
```

--------------------------------

### sbx.desktop.status

Source: https://instabox.sh/docs/sdk

Returns the current desktop status, including whether it is installed and running, and the screen dimensions if running.

```APIDOC
## sbx.desktop.status

### Description
Returns the current desktop status, including whether it is installed and running, and the screen dimensions if running.

### Method
status

### Signature
status(): Promise<DesktopStatus>

### Returns
- Promise<DesktopStatus> - An object with `installed` (boolean), `running` (boolean), and `width` and `height` (numbers) while running.

### Notes
- The desktop runs on X display `:1` (DESKTOP_DISPLAY).
```

--------------------------------

### Create a key

Source: https://instabox.sh/docs/keys-sdk

Instructions for creating an API key with full or restricted access, including available scopes and environment variable setup.

```APIDOC
## Create a key

### Description
Create an API key with full access or restricted scopes. The key is used by the SDK, HTTP, CLI, and SSH.

### Scopes
- `machines:read` - list and get machines, operations, metrics and usage
- `machines:write` - create, start, stop, pause, resume, set auto-pause and labels, exec and SSH
- `machines:delete` - delete machines
- `images:read`, `images:write`, `images:delete` - list, save and delete snapshots

### Environment Variables
- `INSTABOX_API_KEY` - The API key (e.g., `ibk_...`)
- `INSTABOX_API_URL` - The API base URL (e.g., `https://api.instabox.sh`)

### Notes
- The secret is shown only once.
- Revoking a key ends its SSH certificates.
- Keys cannot create keys.
- A key with `machines:write` can select org Secrets for a sandbox and execute code there.
- For a fresh sandbox that should receive credentials from neither store, pass `"vault": false, "secrets": [], "envSecrets": []` to the creation API.
```

--------------------------------

### Response for exec command

Source: https://instabox.sh/docs/api/commands

Example 200 OK response showing stdout, stderr, exit code, and timeout/truncation flags.

```json
{
  "stdout": "hello\n",
  "stderr": "",
  "exitCode": 0,
  "timedOut": false,
  "truncated": false
}
```

--------------------------------

### Get SSH certificate response

Source: https://instabox.sh/docs/api/ssh

Example 201 Created response for getting an SSH certificate. Contains the certificate, host, port, username, and host trust information.

```json
{
  "id": "cn_t5mq2xk7bz4rn3wd6vp2hj4sye",
  "machineId": "m_agqteugyy5px6hzeadbh4ldjo4",
  "transport": "ssh",
  "host": "api.instabox.sh",
  "port": 2222,
  "username": "m_agqteugyy5px6hzeadbh4ldjo4",
  "certificate": "ssh-ed25519-cert-v01@openssh.com AAAA…",
  "expiresAt": "2026-10-13T11:31:07Z",
  "hostTrust": { "type": "ca", "publicKey": "ssh-ed25519 AAAA…", "principals": ["api.instabox.sh"] }
}
```

--------------------------------

### POST /v1/machines/{id}/start

Source: https://instabox.sh/docs/api/lifecycle

Boots a stopped machine. On a paused one it resumes it, or boots fresh if its programs cannot be brought back.

```APIDOC
## POST /v1/machines/{id}/start

### Description
Boots a stopped machine. On a paused one it resumes it, or boots fresh if its programs cannot be brought back.

### Method
POST

### Endpoint
/v1/machines/{id}/start

### Parameters
#### Path Parameters
- **id** (string) - Required - The machine's ID (`m_agqteugyy5px6hzeadbh4ldjo4`).

#### Headers
- **Idempotency-Key** (string) - Required - A unique string, such as a UUID; a retry with the same key is not applied twice (see the API overview).

### Request Example
```
curl -X POST https://api.instabox.sh/v1/machines/m_agqteugyy5px6hzeadbh4ldjo4/start -H "X-API-Key: $INSTABOX_API_KEY" -H "Idempotency-Key: $(uuidgen)"
```

### Response
#### Success Response (202 Accepted)
- **id** (string) - Operation ID.
- **machineId** (string) - The machine's ID.
- **type** (string) - Operation type (e.g., "start").
- **state** (string) - Operation state (e.g., "queued").
- **error** (null) - Error information, if any.
- **createdAt** (string) - Creation timestamp.
- **updatedAt** (string) - Last update timestamp.

#### Response Example
```
{
  "id": "op_7xk2mq4tz5rbw3vn6pd2hs4jye",
  "machineId": "m_agqteugyy5px6hzeadbh4ldjo4",
  "type": "start",
  "state": "queued",
  "error": null,
  "createdAt": "2026-10-13T09:12:04Z",
  "updatedAt": "2026-10-13T09:12:04Z"
}
```
```

--------------------------------

### Inspect sandbox secrets response

Source: https://instabox.sh/docs/api/secrets

Example 200 OK response for the GET secrets request. Shows empty selections and pending proxy/guest delivery states.

```json
{"secrets":[],"envSecrets":[],"items":[],"version":1,"proxy":{"state":"pending","revision":2,"appliedRevision":1},"guest":{"state":"pending","revision":2,"appliedRevision":1,"items":[]}}
```

--------------------------------

### GET /v1/snapshots/{id}/files

Source: https://instabox.sh/docs/api/snapshots

Lists a directory or returns a text file from the snapshot's saved software, without starting a machine. Files under /data are not shown.

```APIDOC
## GET /v1/snapshots/{id}/files

### Description
Lists a directory or returns a text file from the snapshot's saved software, without starting a machine. Files under /data are not shown.

### Method
GET

### Endpoint
/v1/snapshots/{id}/files

### Parameters
#### Path Parameters
- **id** (string) - Required - The snapshot's ID.

#### Query Parameters
- **path** (string) - Optional - An absolute path. Default: `/`.

### Request Example
```
curl "https://api.instabox.sh/v1/snapshots/sn_q4mz7tk2bx5rn3wd6vp2hj4sye/files?path=/etc" -H "X-API-Key: $INSTABOX_API_KEY"
```

### Response
#### Success Response (200 OK)
- **path** (string) - The requested path.
- **type** (string) - Type of the entry (e.g., `dir`, `file`, `symlink`).
- **size** (integer) - Size in bytes.
- **mode** (string) - File mode string.
- **modTime** (string) - Last modification time.
- **entries** (array) - List of directory entries (if directory).

#### Response Example
```
{
  "path": "/etc",
  "type": "dir",
  "size": 0,
  "mode": "drwxr-xr-x",
  "modTime": "2026-10-13T08:01:55Z",
  "entries": [
    { "name": "apt", "type": "dir", "size": 0, "mode": "drwxr-xr-x", "modTime": "2026-10-13T08:01:40Z" },
    { "name": "os-release", "type": "symlink", "size": 21, "mode": "lrwxrwxrwx", "modTime": "2026-10-13T08:01:12Z", "target": "../usr/lib/os-release" },
    …
  ]
}
```
```

--------------------------------

### Sandbox.connect(sandboxId, opts?)

Source: https://instabox.sh/docs/sdk

Attaches to an existing machine and resumes it if it is paused or stopped. Use resume: false to attach without waking it. envs works as in create.

```APIDOC
## Sandbox.connect(sandboxId, opts?)

### Description
Attaches to an existing machine and resumes it if it is paused or stopped. Use `resume: false` to attach without waking it. `envs` works as in `create`.

### Method
connect

### Signature
`Sandbox.connect(sandboxId: string, opts?: SandboxConnectOpts): Promise<Sandbox>`

### Parameters
- **sandboxId** (string) - Required - The ID of the sandbox to connect to.
- **opts** (SandboxConnectOpts) - Optional - Options for the connection, including `resume` and `envs`.
```

--------------------------------

### TypeScript SDK usage example

Source: https://instabox.sh/docs/keys-sdk

Creates a sandbox, runs commands, writes/reads files, pauses, reconnects, lists, and kills. Uses environment variables or options for API key and URL.

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

const sbx = await Sandbox.create('universal', {   // a template, a snapshot name, or a snapshot ID
  metadata: { task: 'review' },
})
const r = await sbx.commands.run('uname -a')         // throws CommandExitError on a non-zero exit
console.log(r.stdout)
await sbx.files.write('/data/home/notes.txt', 'hello')
console.log(await sbx.files.read('/data/home/notes.txt'))

await sbx.pause()                                   // pause; memory is kept
const again = await Sandbox.connect(sbx.sandboxId)   // resumes it
await Sandbox.list({ metadata: { task: 'review' } })
await again.kill()                                  // delete
```

--------------------------------

### GET /v1/machines/{id}

Source: https://instabox.sh/docs/api/machines

Gets a single machine by its ID.

```APIDOC
## GET /v1/machines/{id}

### Description
Gets a single machine by its ID.

### Method
GET

### Endpoint
/v1/machines/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The machine ID, starting with `m_` and 26 characters.

### Response
#### Success Response (200)
- **id** (string) - Machine ID.
- **name** (string) - Machine name.
- **state** (string) - Current state.
- **operationId** (string|null) - Operation in progress, if any.
- **template** (object) - Template info: `id`, `version`, `digest`.
- **spec** (object) - Size: `vcpus`, `memMiB`, `persistentDiskGiB`, `rootDiskGiB`.
- **runtime** (object) - `ready` is true once it runs and passes its checks.
- **autoSuspendAfterSeconds** (integer|null) - Idle time before pause.
- **metadata** (object) - Your labels.
- **createdAt** (string) - Creation timestamp.

#### Response Example
```
{
  "id": "m_agqteugyy5px6hzeadbh4ldjo4",
  "name": "dev",
  "state": "running",
  "operationId": null,
  "template": {
    "id": "universal",
    "version": "1.0",
    "digest": "sha256:..."
  },
  "spec": {
    "vcpus": 4,
    "memMiB": 8192,
    "persistentDiskGiB": 20,
    "rootDiskGiB": 10
  },
  "runtime": {
    "ready": true
  },
  "autoSuspendAfterSeconds": 1800,
  "metadata": {},
  "createdAt": "2026-10-13T09:12:04Z"
}
```
```

--------------------------------

### Save a snapshot and create a machine from it

Source: https://instabox.sh/docs/snapshots

Use these CLI commands to save a snapshot named 'dev-base' from the 'dev' machine, create a new machine 'dev2' from that snapshot, and list available snapshots.

```bash
instabox snapshot save dev --name dev-base
instabox create --name dev2 --snapshot dev-base
instabox snapshot ls
```

--------------------------------

### Get a snapshot (GET /v1/snapshots/{id})

Source: https://instabox.sh/docs/api/snapshots

Returns details for a single snapshot, identified by its ID.

```bash
curl https://api.instabox.sh/v1/snapshots/sn_q4mz7tk2bx5rn3wd6vp2hj4sye -H "X-API-Key: $INSTABOX_API_KEY"
```

```json
{
  "id": "sn_q4mz7tk2bx5rn3wd6vp2hj4sye",
  "name": "dev-base",
  "sourceMachineId": "m_agqteugyy5px6hzeadbh4ldjo4",
  "sourceSnapshotSeq": 7,
  "status": "ready",
  "template": { "id": "universal", "version": "2026-10-13.10", "digest": "sha256:9f2c…" },
  "rootSizeBytes": 17179869184,
  "dataSizeBytes": 21474836480,
  "createdAt": "2026-10-13T10:02:11Z"
}
```

--------------------------------

### Install mosh on macOS

Source: https://instabox.sh/docs/ssh

Install mosh on macOS using Homebrew. Required to use mosh with instabox.

```bash
brew install mosh
```

--------------------------------

### Start a machine with curl

Source: https://instabox.sh/docs/api/lifecycle

Sends a POST request to /v1/machines/{id}/start to boot a stopped machine or resume a paused one. Requires an Idempotency-Key header.

```bash
curl -X POST https://api.instabox.sh/v1/machines/m_agqteugyy5px6hzeadbh4ldjo4/start -H "X-API-Key: $INSTABOX_API_KEY" -H "Idempotency-Key: $(uuidgen)"
```

--------------------------------

### sbx.desktop.open(url)

Source: https://instabox.sh/docs/integrate

Opens a URL in the desktop's browser.

```APIDOC
## sbx.desktop.open(url)

### Description
Opens a URL in the desktop's browser.

### Method
open

### Parameters
#### Path Parameters
- **url** (string) - Required - The URL to open.

### Request Example
```javascript
await sbx.desktop.open('https://example.com')
```

### Response
#### Success Response
No return value documented.
```

--------------------------------

### Get current user - curl request

Source: https://instabox.sh/docs/api/account

Sends a GET request to /v1/me with an API key header to retrieve the user associated with the key.

```bash
curl https://api.instabox.sh/v1/me -H "X-API-Key: $INSTABOX_API_KEY"
```

--------------------------------

### Get usage and limits - curl request

Source: https://instabox.sh/docs/api/account

Sends a GET request to /v1/usage with an API key header to retrieve machine and snapshot counts, stored bytes, and limits.

```bash
curl https://api.instabox.sh/v1/usage -H "X-API-Key: $INSTABOX_API_KEY"
```

--------------------------------

### List templates - 200 OK response

Source: https://instabox.sh/docs/api/account

Example JSON response from /v1/templates showing a template object with id, version, description, arch, and defaultSpec.

```json
{
  "templates": [
    {
      "id": "universal",
      "version": "2026-10-13.10",
      "description": "dev plus Docker, Python (uv), Go and Rust",
      "arch": "x86_64",
      "defaultSpec": { "vcpus": 4, "memMiB": 8192, "persistentDiskGiB": 20 },
      …
    }
  ]
}
```

--------------------------------

### HTTP API lifecycle and exec calls with curl

Source: https://instabox.sh/docs/keys-sdk

Shows how to create a machine, poll an operation, exec a command, and delete a machine using the X-API-Key header and Idempotency-Key.

```bash
H="X-API-Key: $INSTABOX_API_KEY"
curl -s -H "$H" -H "Idempotency-Key: $(uuidgen)" -H 'Content-Type: application/json' \
  -d '{"name": "box", "templateId": "herdr"}' "$INSTABOX_API_URL/v1/machines"
curl -s -H "$H" "$INSTABOX_API_URL/v1/operations/op_...?wait=25s"  # long poll, until "state": "succeeded"
curl -s -H "$H" -H 'Content-Type: application/json' \
  -d '{"cmd": "uname -a", "timeoutSeconds": 60}' "$INSTABOX_API_URL/v1/machines/m_.../exec"
curl -s -X DELETE -H "$H" -H "Idempotency-Key: $(uuidgen)" "$INSTABOX_API_URL/v1/machines/m_..."
```

--------------------------------

### sbx.desktop.screenshot()

Source: https://instabox.sh/docs/integrate

Takes a screenshot of the desktop.

```APIDOC
## sbx.desktop.screenshot()

### Description
Takes a screenshot of the desktop.

### Method
screenshot

### Parameters
None

### Request Example
```javascript
const png = await sbx.desktop.screenshot()
```

### Response
#### Success Response
- **png** (Buffer) - The screenshot image data.
```

--------------------------------

### Get SSH certificate with curl

Source: https://instabox.sh/docs/api/ssh

Sends a POST request to get an SSH certificate for a machine. Requires an Idempotency-Key and your public key. The machine must be running or paused for being idle.

```bash
curl -X POST https://api.instabox.sh/v1/machines/m_agqteugyy5px6hzeadbh4ldjo4/connections -H "X-API-Key: $INSTABOX_API_KEY" -H "Idempotency-Key: $(uuidgen)" -H 'Content-Type: application/json' \
  -d "{\"publicKey\": \"$(cat ~/.ssh/id_ed25519.pub)\"}"
```

--------------------------------

### Sandbox.list(opts?)

Source: https://instabox.sh/docs/sdk

Returns every page of your machines. The metadata option keeps only those with every given key and value.

```APIDOC
## Sandbox.list(opts?)

### Description
Returns every page of your machines. The `metadata` option keeps only those with every given key and value.

### Method
list

### Signature
`Sandbox.list(opts?: SandboxListOpts): Promise<SandboxInfo[]>`

### Parameters
- **opts** (SandboxListOpts) - Optional - Options for listing, including `metadata`.
```

--------------------------------

### GET /v1/machines

Source: https://instabox.sh/docs/api/machines

Lists all machines.

```APIDOC
## GET /v1/machines

### Description
Lists all machines.

### Method
GET

### Endpoint
/v1/machines

### Response
#### Success Response (200)
- **machines** (array) - List of machine objects.

#### Response Example
```
{
  "machines": [
    {
      "id": "m_agqteugyy5px6hzeadbh4ldjo4",
      "name": "dev",
      "state": "running",
      "operationId": null,
      "template": {
        "id": "universal",
        "version": "1.0",
        "digest": "sha256:..."
      },
      "spec": {
        "vcpus": 4,
        "memMiB": 8192,
        "persistentDiskGiB": 20,
        "rootDiskGiB": 10
      },
      "runtime": {
        "ready": true
      },
      "autoSuspendAfterSeconds": 1800,
      "metadata": {},
      "createdAt": "2026-10-13T09:12:04Z"
    }
  ]
}
```
```

--------------------------------

### Set secrets, create sandbox, and show secrets with Instabox CLI

Source: https://instabox.sh/docs/secrets

Commands to set secrets with proxy or env delivery, create a sandbox with all secrets or specific env secrets, and show secrets for an app. Requires signing in as an org owner or admin. Values are read from stdin or a prompt without echo.

```bash
instabox secrets set SERVICE_API_KEY --org team --delivery proxy --host api.example.com
instabox secrets set DATABASE_URL --org team --delivery env
instabox create --name app --org team --secrets all --env-secrets DATABASE_URL
instabox secrets show app
```

--------------------------------

### GET /v1/ports

Source: https://instabox.sh/docs/api/ports

Lists the public ports of all your machines.

```APIDOC
## GET /v1/ports

### Description
The public ports of all your machines.

### Method
GET

### Endpoint
/v1/ports

### Request Example
```
curl https://api.instabox.sh/v1/ports -H "X-API-Key: $INSTABOX_API_KEY"
```

### Response
#### Success Response (200 OK)
- **enabled** (boolean) - Whether public ports are enabled.
- **ports** (array) - List of port objects.

#### Response Example
```
{ "enabled": true, "ports": [ … ] }
```
```

--------------------------------

### desktop

Source: https://instabox.sh/docs/sdk

See and control the desktop.

```APIDOC
## desktop

### Description
See and control the desktop.

### Type
`Desktop`
```

--------------------------------

### Create and list machines with metadata labels

Source: https://instabox.sh/docs/machines

Creates a machine with a label and lists machines with that label. The comment shows the corresponding API endpoint.

```bash
instabox create --name job --meta task=review
instabox ls --meta task=review     # GET /v1/machines?metadata=task:review
```

--------------------------------

### List a machine's ports: 200 OK response

Source: https://instabox.sh/docs/api/ports

Example response body for listing a machine's ports. Shows an enabled flag and an array of port objects with port, name, and url.

```json
{ "enabled": true, "ports": [ { "port": 3000, "name": "Web app", "url": "https://3000-agqteugyy5px6hzeadbh4ldjo4.instabox.tech", … } ] }
```

--------------------------------

### resume()

Source: https://instabox.sh/docs/sdk

Resumes a paused machine, or starts a stopped one.

```APIDOC
## resume()

### Description
Resumes a paused machine, or starts a stopped one.

### Method
`resume()`

### Returns
`Promise<void>`
```

--------------------------------

### SDK: Get desktop status

Source: https://instabox.sh/docs/desktop

Returns the status of the desktop session.

```APIDOC
## SDK: Get desktop status

### Description
Returns the status of the desktop session.

### Method
SDK Method

### Endpoint
`sbx.desktop.status()`

### Parameters
None

### Request Example
```javascript
const status = await sbx.desktop.status()
```

### Response
- **status** (object) - Status information of the desktop.
```

--------------------------------

### SDK: Get cursor position

Source: https://instabox.sh/docs/desktop

Returns the current cursor position.

```APIDOC
## SDK: Get cursor position

### Description
Returns the current cursor position.

### Method
SDK Method

### Endpoint
`sbx.desktop.cursorPosition()`

### Parameters
None

### Request Example
```javascript
const pos = await sbx.desktop.cursorPosition()
```

### Response
- **pos** (object) - Contains x and y coordinates.
```

--------------------------------

### GET /v1/snapshots/{id}

Source: https://instabox.sh/docs/api/snapshots

Retrieves details of a single snapshot by its ID.

```APIDOC
## GET /v1/snapshots/{id}

### Description
Retrieves details of a single snapshot by its ID.

### Method
GET

### Endpoint
/v1/snapshots/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The snapshot's ID.

### Request Example
```
curl https://api.instabox.sh/v1/snapshots/sn_q4mz7tk2bx5rn3wd6vp2hj4sye -H "X-API-Key: $INSTABOX_API_KEY"
```

### Response
#### Success Response (200 OK)
- **id** (string) - Snapshot ID.
- **name** (string) - Snapshot name.
- **sourceMachineId** (string) - The machine it was saved from.
- **sourceSnapshotSeq** (integer) - Sequence number of the snapshot.
- **status** (string) - Status of the snapshot.
- **template** (object) - Template information.
- **rootSizeBytes** (integer) - Size of the saved system disk.
- **dataSizeBytes** (integer) - Size of the saved storage disk.
- **createdAt** (string) - When it was saved.

#### Response Example
```
{
  "id": "sn_q4mz7tk2bx5rn3wd6vp2hj4sye",
  "name": "dev-base",
  "sourceMachineId": "m_agqteugyy5px6hzeadbh4ldjo4",
  "sourceSnapshotSeq": 7,
  "status": "ready",
  "template": { "id": "universal", "version": "2026-10-13.10", "digest": "sha256:9f2c…" },
  "rootSizeBytes": 17179869184,
  "dataSizeBytes": 21474836480,
  "createdAt": "2026-10-13T10:02:11Z"
}
```
```

--------------------------------

### Read a snapshot's files (GET /v1/snapshots/{id}/files)

Source: https://instabox.sh/docs/api/snapshots

Lists a directory or returns a text file from the snapshot's saved software. The 'path' query parameter defaults to '/'. Files under '/data' are not shown.

```bash
curl "https://api.instabox.sh/v1/snapshots/sn_q4mz7tk2bx5rn3wd6vp2hj4sye/files?path=/etc" -H "X-API-Key: $INSTABOX_API_KEY"
```

```json
{
  "path": "/etc",
  "type": "dir",
  "size": 0,
  "mode": "drwxr-xr-x",
  "modTime": "2026-10-13T08:01:55Z",
  "entries": [
    { "name": "apt", "type": "dir", "size": 0, "mode": "drwxr-xr-x", "modTime": "2026-10-13T08:01:40Z" },
    { "name": "os-release", "type": "symlink", "size": 21, "mode": "lrwxrwxrwx", "modTime": "2026-10-13T08:01:12Z", "target": "../usr/lib/os-release" },
    …
  ]
}
```