> ## Documentation Index
> Fetch the complete documentation index at: https://instabox.sh/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Run a multi-tenant compute platform

> Create machines for your own customers from one workspace and one API key, and read what each customer used at list price.

If you run a platform, a marketplace, or an agent product, you can offer your customers machines
without giving them InstaBox accounts. You hold one workspace and one API key on your server, create
a machine for each customer, and label it with that customer's ID. At the end of a period you read
what each customer's machines used, at list price, and bill it your own way.

## Pick a plan

A multi-tenant platform runs on the same plans as any other workspace. Start on a standard plan, and
move to Enterprise when you need billing terms of your own.

| You want | Plan | How you pay |
| - | - | - |
| To start now, with a card | Pro, Builder, or Team | The plan's monthly fee, which is also the usage the month includes, then usage beyond it at list price |
| Custom billing, limits, or terms | Enterprise | Terms agreed with us |

[Pricing](https://instabox.sh/docs/account/pricing.md) has each plan's fee and unit prices, and [Limits](https://instabox.sh/docs/account/limits.md) has how
many machines each plan can hold and run at once. For Enterprise, contact us at
[https://instabox.sh/contact](https://instabox.sh/contact).

The plan changes only what your workspace pays. The steps below, and the prices you read for each
customer, are the same on every plan.

## Set up and run machines

**1. Make a key for your workspace**

Make one key that belongs to your workspace, because a key reaches only the workspace it belongs
to. Give it the scopes your server needs and nothing else, so that it cannot change members or
Secrets.

```bash theme={null}
instabox keys create --name platform --org my-platform \
  --scope machines:read,machines:write,machines:delete,images:read
```

The command prints the key once. Store it on your server and set it for the calls below. The SDKs
read it from the same variable.

```bash theme={null}
export INSTABOX_API_KEY=ibk_...
```

Your customers never see this key. They sign in to your product, and your server calls InstaBox
for them.

**2. Create a machine for a customer**

Create the machine with your customer's ID in `metadata`. The label is how you find the
customer's machines and add up their usage later.

```ts TypeScript theme={null}
import { Sandbox } from '@insforge/instabox-sdk'

const sbx = await Sandbox.create('agent-browser', {
  metadata: { customer: 'acme' },
})
console.log(sbx.sandboxId)
```

```python Python theme={null}
from instabox import Client

client = Client()
machine = client.machines.create(
    "acme-1",
    metadata={"customer": "acme"},
)
print(machine.id)
```

```bash API theme={null}
curl -X POST https://api.instabox.sh/v1/machines \
  -H "X-API-Key: $INSTABOX_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name": "acme-1", "metadata": {"customer": "acme"}}'
```

The SDK calls wait until the machine runs and give you its ID, `m_...`. Store that ID with your
customer. The API call returns an operation with the ID in `machineId`, and you follow the
operation until its `state` is `succeeded`.

```bash theme={null}
curl "https://api.instabox.sh/v1/operations/op_...?wait=25s" \
  -H "X-API-Key: $INSTABOX_API_KEY"
```

A machine can carry up to 32 labels. You can add a second label, such as `plan` or `project`, when
you need to split one customer's usage further.

**3. Find a customer's machines**

List the machines that carry the customer's label. The list has only the machines whose
`customer` label is exactly `acme`.

```ts TypeScript theme={null}
const machines = await Sandbox.list({
  metadata: { customer: 'acme' },
})
```

```python Python theme={null}
machines = client.machines.list(metadata={"customer": "acme"})
```

```bash API theme={null}
curl "https://api.instabox.sh/v1/machines?metadata=customer:acme" \
  -H "X-API-Key: $INSTABOX_API_KEY"
```

To match on two labels, give both. Over the API, repeat the `metadata` parameter.

**4. Pause and resume it**

Pause a machine when your customer is not using it, because a paused machine keeps its memory and
files and is not billed for runtime.

```ts TypeScript theme={null}
const sbx = await Sandbox.connect('m_...', { resume: false })
await sbx.pause()
```

```python Python theme={null}
client.machines.pause("m_...")
```

```bash API theme={null}
curl -X POST https://api.instabox.sh/v1/machines/m_.../suspend \
  -H "X-API-Key: $INSTABOX_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
```

Resume it when the customer comes back.

```ts TypeScript theme={null}
await sbx.resume()
```

```python Python theme={null}
client.machines.resume("m_...")
```

```bash API theme={null}
curl -X POST https://api.instabox.sh/v1/machines/m_.../resume \
  -H "X-API-Key: $INSTABOX_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
```

[Lifecycle](https://instabox.sh/docs/machines/lifecycle.md) has every state and what each one bills.

**5. Delete it**

Delete the machine when the customer is done. Over the API and in Python, you repeat the machine's
ID to confirm, so that a mistyped ID cannot delete another customer's machine.

```ts TypeScript theme={null}
await Sandbox.kill('m_...')
```

```python Python theme={null}
client.machines.delete("m_...", confirm="m_...")
```

```bash API theme={null}
curl -X DELETE https://api.instabox.sh/v1/machines/m_... \
  -H "X-API-Key: $INSTABOX_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "X-Confirm-Delete: m_..."
```

A deleted machine's usage is kept, so you can still bill the customer for it.

## Read what a customer used

Ask for the usage of the customer's machines over the period you bill, with the same label filter.
The SDKs do not wrap this endpoint yet, so the TypeScript and Python examples call it over HTTP.

```ts TypeScript theme={null}
const params = new URLSearchParams({
  metadata: 'customer:acme',
  from: '2026-11-01T00:00:00Z',
  to: '2026-12-01T00:00:00Z',
  limit: '100',
})
const res = await fetch(
  `https://api.instabox.sh/v1/usage/machines?${params}`,
  { headers: { 'X-API-Key': process.env.INSTABOX_API_KEY! } },
)
const { machines } = await res.json()

let total = 0
for (const m of machines) {
  total += m.computeUSD + m.diskUSD + m.egressUSD
}
console.log(total)
```

```python Python theme={null}
import json
import os
import urllib.parse
import urllib.request

params = urllib.parse.urlencode({
    "metadata": "customer:acme",
    "from": "2026-11-01T00:00:00Z",
    "to": "2026-12-01T00:00:00Z",
    "limit": 100,
})
req = urllib.request.Request(
    f"https://api.instabox.sh/v1/usage/machines?{params}",
    headers={"X-API-Key": os.environ["INSTABOX_API_KEY"]},
)
with urllib.request.urlopen(req) as res:
    machines = json.load(res)["machines"]

total = sum(
    m["computeUSD"] + m["diskUSD"] + m["egressUSD"] for m in machines
)
print(total)
```

```bash API theme={null}
curl -G https://api.instabox.sh/v1/usage/machines \
  -H "X-API-Key: $INSTABOX_API_KEY" \
  -d metadata=customer:acme \
  -d from=2026-11-01T00:00:00Z \
  -d to=2026-12-01T00:00:00Z \
  -d limit=100
```

Each row of the response is one machine, with what it used and the price of that use.

```json theme={null}
{
  "from": "2026-11-01T00:00:00Z",
  "to": "2026-12-01T00:00:00Z",
  "total": 1,
  "machines": [
    {
      "id": "m_...",
      "name": "acme-1",
      "metadata": { "customer": "acme" },
      "free": false,
      "runningSeconds": 3600,
      "vcpuSeconds": 14400,
      "memGiBSeconds": 28800,
      "computeUSD": 0.034,
      "diskGiBSeconds": 1728000,
      "diskUSD": 0.0528,
      "egressBytes": 1073741824,
      "egressUSD": 0.02
    }
  ]
}
```

The sum of `computeUSD`, `diskUSD`, and `egressUSD` over the rows is the customer's total. A machine
that the customer deleted during the period is still in the list, with `deletedAt` set. When `total`
is larger than the rows you got, read the next page with `offset`.

## What the prices mean

The three prices on a row are list prices: the machine's use times the unit prices on
[Pricing](https://instabox.sh/docs/account/pricing.md). The unit prices are the same on every paid plan, so a paid machine's
price does not depend on your plan or on what the plan includes. A free machine's three prices are 0,
and disk is not priced while the workspace is on the free plan.

Your own bill can be lower than the sum of the rows. A plan's monthly allowance, its included disk,
and its included egress belong to the whole workspace and not to one machine, so they come off the
workspace's total. To see what your workspace owes after those, read
[Billing and usage](https://instabox.sh/docs/account/billing.md).

| You want | Read | Price |
| - | - | - |
| What one customer used | `GET /v1/usage/machines` with `metadata` | List price for each machine |
| What your workspace owes | `GET /v1/usage` | After what your plan includes |

## React to changes without polling

You can register a webhook for your workspace, so that your server learns when a customer's machine
is ready, pauses, fails, or is deleted. See [Webhooks](https://instabox.sh/docs/integrations/webhooks.md).

## Limits

* A key cannot make another key. You make and revoke keys while signed in.
* The window of a usage request can be at most 366 days.
* Egress is counted by whole hour, so a window that starts inside an hour includes that whole hour.

> [card] [API keys](https://instabox.sh/docs/security/api-keys.md)
>
> Scopes, and which workspace a key reaches.

> [card] [SDK quick start](https://instabox.sh/docs/integrations/sdk-quickstart.md)
>
> Install the SDK, run commands, and move files.

> [card] [Billing and usage](https://instabox.sh/docs/account/billing.md)
>
> Your workspace's cost and credits this month.

> [card] [API overview](https://instabox.sh/docs/api-reference/introduction.md)
>
> Authentication, operations, idempotency, and errors.
