Skip to content

docs(cloud): restructure the Cloud tab and add verified pricing pages #33

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Mandalorian-Wang merged 3 commits into from
Aug 27, 2026
Merged

docs(cloud): restructure the Cloud tab and add verified pricing pages #33

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
8164102
docs: generate llms.txt instead of maintaining it by hand
Mandalorian-Wang Aug 21, 2026
107f483
docs: rewrite Cloud volumes against main, split operations, fix tab name
Mandalorian-Wang Aug 27, 2026
ac62b65
docs(cloud): restructure the Cloud tab and add verified pricing pages
Mandalorian-Wang Aug 27, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .github/workflows/docs-lint.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,3 +15,5 @@ jobs:
python-version: "3.12"
- name: No soft promises (AGENTS.md)
run: python3 scripts/lint-docs.py .
- name: llms.txt matches docs.json and page frontmatter
run: python3 scripts/gen-llms-txt.py --check
124 changes: 51 additions & 73 deletions cloud/billing.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,107 +1,85 @@
---
title: "Plans, wallet, and usage"
sidebarTitle: "Billing"
description: "How BoxLite Cloud charges for boxes: a plan gives you included quota and a concurrency limit each cycle, and your prepaid wallet funds everything beyond it."
title: "Managing billing"
sidebarTitle: "Managing billing"
description: "Fund your wallet, set automatic reload so boxes never stop for lack of balance, read what you have actually been charged, and know the per-box ceilings that apply to every box in your organization."
---

A plan gives you two things each billing cycle: an included quota of usage and a concurrency limit on how many boxes run at once. The wallet is a prepaid balance that funds usage once that quota is consumed. Everything on this page lives under **Billing** in the console, across its **Overview**, **Usage**, and **Wallet** tabs.
This page covers running the account. For what a box costs see [What a box costs](/cloud/box-costs); for whether to subscribe see [Wallet or a plan?](/cloud/plans).

## How usage is funded
Your **wallet** is a prepaid balance. It funds usage once a plan's included quota is consumed, and it funds everything if you have no plan.

The console states the rule on its own usage chart: **quota covers first, the wallet funds the rest**. Two separate ideas sit behind that sentence.
## The wallet

**Included quota** comes with a plan. It is an amount of usage — expressed in dollars — that your plan covers during the current billing cycle. You do not top it up and you do not manage it; it arrives with the plan and is tied to the cycle.
The **Wallet** tab shows your available balance and what you have spent this month.

**Wallet balance** is prepaid and entirely yours to manage. You add funds to it, and it pays for usage after the cycle's included quota is consumed. An account can hold a wallet balance with or without a plan.
<Note>
The figure shown as **available** is your *ongoing* balance: it already reflects usage accrued this cycle but not yet settled. That is why it drifts downward while boxes run, with no payment having been taken.
</Note>

So a box you run draws on your quota until the quota for that cycle is gone, and from that point on it draws on your wallet.

The **New box** dialog reports a box's **PRICE PER HOUR** before you create it, so you can see what a size costs while you are choosing it.

## Plans

The **Overview** tab lists the available plans and marks your **ACTIVE PLAN**.

| Plan | Price | Included quota | Concurrency limit |
|---|---|---|---|
| Starter | $19/mo | $30 | 20 boxes |
| Pro | $149/mo | $250 | 100 boxes |
| Max | $499/mo | $900 | 1000 boxes |

**Enterprise** is handled directly: custom limits and compliance review. Contact sales at [sales@boxlite.ai](mailto:sales@boxlite.ai).

### What the concurrency limit means for you

The concurrency limit caps how many boxes run at the same time — not how many you create over a month, and not how much work each one does. If you are building an agent fleet, this is the number to size against your workload: an orchestrator that fans out to 40 parallel agents, each in its own box, needs a plan whose concurrency limit clears 40. A single long-lived box that runs all day occupies one slot the whole time.

Quota and concurrency are independent. You can hit the concurrency limit with quota to spare, and you can exhaust quota while running a single box.

### Accounts with no plan

An account does not have to carry a plan. The console shows **ACTIVE PLAN** as `No plan` in that case, and usage draws on the wallet balance instead of on an included quota. Pick a plan from **ALL PLANS** on the **Overview** tab when you want a cycle quota and a plan concurrency limit.

## Per-box resource ceilings

**Billing** also publishes the resource ceilings that apply to every box in your organization, under **BOX LIMITS** — "Resources limit per box":

| Resource | Ceiling per box |
|---|---|
| Compute | 4 vCPU |
| Memory | 32 GiB |
| Storage | 120 GiB |
### Add funds

The console gives its reason plainly: limits mitigate misuse and keep box and compute capacity fairly available across all users.
Click **Top up** and pick a preset amount — **$25**, **$500**, **$1,000**, or **$2,000** — or enter a custom amount. The console redirects you to Stripe to complete the payment.

These are ceilings on a **single box**, which makes them a different constraint from your plan's concurrency limit. The ceilings bound how large one box can be; the concurrency limit bounds how many boxes run at once. See [Boxes](/cloud/boxes) for the preset sizes and the custom size fields you choose from within these ceilings. If your workload genuinely needs a larger single box, that is an Enterprise conversation — custom limits go through [sales@boxlite.ai](mailto:sales@boxlite.ai).
### Set automatic reload

## Wallet
Manual top-ups are why wallets hit zero at 3am. Automatic reload watches the balance and refills it: set a **threshold** to drop below and a **target** to be refilled to, and the console reads the result back as `Below $20.00 → $100.00`.

The **Wallet** tab shows **WALLET BALANCE** (the amount available) and **SPENT THIS MONTH**. The balance is prepaid: you put money in before you spend it, and it funds usage beyond your plan's included quota.
It prefills $20 and $100. Reload stays off until you save it, and it charges your connected card — so attach one first.

### Add funds
### Connect a payment method

Click **Top up** and choose one of the preset amounts — **$25**, **$500**, **$1,000**, or **$2,000** — or enter a custom amount. The console tells you what happens next: "You will be redirected to Stripe to complete the payment."
Until a card is attached the console shows the payment method as not connected, with a **Connect** button beside it. Connecting one earns an additional **$100 of credits**.

### Redeem a coupon

**REDEEM COUPON** takes a coupon code and credits your account: "Enter a coupon code to redeem your credits."

### Connect a payment method

Until you attach a card, **PAYMENT METHOD** reads `Payment method not connected`, with a **Connect** button beside it. The console attaches an offer to doing so, in its own words: "Connect a credit card to receive an additional $100 of credits."

## Track usage
**Redeem coupon** takes a coupon code and credits the account. Credits are tracked separately from your topped-up balance, so the console shows credits remaining against credits granted.

The **Usage** tab answers the question "where is my money going" with **COST OVER TIME** — settled cost by day for the last 30 days, viewable as either a **CHART** or a **LIST**.
## Read the usage chart

The view splits cost into two series:
The **Usage** tab answers "where is my money going" with settled cost by day for the last 30 days, as either a chart or a list. It splits cost into two series:

| Series | What it represents |
|---|---|
| **Quota-covered** | Cost your plan's included quota absorbed |
| **From wallet** | Cost your prepaid wallet balance paid for |

Read it in that order, because it mirrors how funding works. While quota remains for the cycle, the days you see are quota-covered. Once the cycle's quota is consumed, **From wallet** is the series that grows — and that transition is the moment worth watching, because it is where a running box starts drawing on money you topped up.
The moment worth watching is when the second series starts growing: that is where this cycle's quota ran out and your boxes began drawing on money you topped up.

Check this tab **before** you scale a workload up. Look at what a typical day already costs and which series it lands in, then multiply by the fan-out you are about to add. A workload that doubles its box count doubles a quota-covered day just as readily as a wallet-funded one; the difference is only whether you notice.
This tab is the authority on what you were actually charged — the hourly figures in the **New Box** dialog and on [What a box costs](/cloud/box-costs) are estimates. **Check it before you scale a workload up:** see what a typical day already costs, then multiply by the fan-out you are about to add.

## Keep costs predictable
## Per-box resource ceilings

**Billing** also publishes the ceilings that apply to every box in your organization:

| Resource | Ceiling per box |
|---|---|
| Compute | 4 vCPU |
| Memory | 32 GiB |
| Storage | 120 GiB |

The console prices a box per hour, so the habits that keep spend flat are all about not leaving boxes running behind you.
These bound how large a **single box** can be — a different constraint from your plan's concurrency limit, which bounds how many boxes run at once. A request above a ceiling is rejected before the box is created, so you get a clear error rather than a box that fails later. See [Choose a size](/cloud/box-sizes) for the presets and custom fields available within them.

- **Remove boxes when the work is done.** A forgotten box is the most common source of surprise cost. Tear it down as part of your task, not as cleanup you plan to do later. See [Boxes](/cloud/boxes).
- **Treat stop-when-idle as a safety net, not a budget.** It is a genuine backstop for boxes you forgot, but the console is explicit about its blind spot: idle means no SDK, terminal, or preview traffic, and work running inside the box does not count. A busy box is never idle, so stop-when-idle will not cap what it spends.
- **Size the box to the job.** The largest size is not the safe default. Pick the smallest preset that runs your workload comfortably, and reach for a custom size only when a preset genuinely does not fit — see [Boxes](/cloud/boxes).
- **Size your fleet against the concurrency limit.** Know the limit on your plan before you fan out, so an orchestrator does not stall partway through a batch.
- **Look at the Usage tab before a large run.** One glance at the last 30 days tells you whether you are still on quota and what a day of the current workload costs.
If a workload genuinely needs a larger single box, that is an Enterprise conversation — custom limits go through [sales@boxlite.ai](mailto:sales@boxlite.ai).

## Troubleshooting

| Situation | Why it happens | What to do |
|---|---|---|
| New boxes are refused while your existing boxes keep running fine | You are at your plan's concurrency limit — the cap is on boxes running at the same time | Stop or remove a box you no longer need to free a slot, or move to a plan with a higher concurrency limit |
| Your cost is showing up under **From wallet** instead of **Quota-covered** | The included quota for this billing cycle is consumed, so usage now draws on your prepaid balance | Nothing is broken. Keep the wallet funded, or move to a plan whose included quota matches your steady-state usage |
| Wallet balance has reached zero and your quota is consumed | There is nothing left to fund usage this cycle | Click **Top up** on the **Wallet** tab, or redeem a coupon code under **REDEEM COUPON** |
| **ACTIVE PLAN** shows `No plan` | The account carries no subscription, so there is no included quota and no plan concurrency limit | Choose a plan from **ALL PLANS** on the **Overview** tab, or keep running on wallet balance alone if that suits you |
| **PAYMENT METHOD** shows `Payment method not connected` | No card is attached to the account | Click **Connect** on the **Wallet** tab. The console offers additional credits for connecting a credit card |
| A box needs more than 4 vCPU, 32 GiB of memory, or 120 GiB of storage | Those are per-box ceilings for the whole organization | Split the work across several boxes within your concurrency limit, or discuss custom limits with [sales@boxlite.ai](mailto:sales@boxlite.ai) |
| Wallet balance has reached zero and your quota is consumed | There is nothing left to fund usage this cycle | Top up on the **Wallet** tab, or redeem a coupon code |
| Boxes stopped and the console reports credits depleted | Nothing remains to fund them, so the platform stops boxes rather than running up an unfunded bill | Top up, then set automatic reload so it does not recur |
| Automatic reload is configured but never fires | Reload needs a card to charge, and no payment method is connected | Connect a card on the **Wallet** tab |
| The available balance drops while you have taken no payment | The figure is the ongoing balance, which already includes usage accrued but not yet settled | Nothing is wrong. Compare against the **Usage** tab for settled cost |
| The payment method shows as not connected | No card is attached to the account | Click **Connect** on the **Wallet** tab. Connecting one also earns $100 of credits |
| A box request asks for more CPU, memory, or disk than allowed | It exceeds a per-box ceiling for the organization | Lower the request, or spread the work across several boxes within your concurrency limit |
| Cost is higher than expected with no obvious cause | Stopped boxes are still billed for their disk until they are deleted | Delete boxes you have finished with. See [What each box state costs](/cloud/box-costs#what-each-box-state-costs) |

## Next steps

<CardGroup cols={2}>
<Card title="What a box costs" icon="calculator" href="/cloud/pricing">
Rates, worked examples, and the two controls that cap what you keep paying.
</Card>
<Card title="Wallet or a plan?" icon="scale-balanced" href="/cloud/plans">
The usage level at which a subscription starts costing less.
</Card>
</CardGroup>
98 changes: 98 additions & 0 deletions cloud/box-costs.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,98 @@
---
title: "What a box costs"
sidebarTitle: "Box costs"
description: "The three metered rates, the formula they combine into, what the standard sizes come to per hour and per month, and exactly which hours are counted."
---

A box rents three things by the hour: vCPU, memory, and disk. This page turns those rates into the numbers you can plan against.

## Rates

| Resource | Unit | Rate |
|---|---|---|
| vCPU | per vCPU-hour | **$0.0504** |
| Memory | per GiB-hour | **$0.0144** |
| Disk | per GiB-hour | **$0.00018** |

A box's hourly price is the plain sum, with no tiers and no rounding:

```
hourly = vCPU × $0.0504 + memory_GiB × $0.0144 + disk_GiB × $0.00018
```

Nothing else is metered. There is no charge for network traffic, API requests, mounted volumes, preview URLs, or the time a box spends booting.

## What the standard sizes cost

The three sizes in the **New Box** dialog, plus the largest box your organization can request:

| Size | vCPU / memory / disk | Per hour | 30 days running | 30 days stopped |
|---|---|---|---|---|
| **Small** | 1 / 1 GiB / 10 GiB | $0.0666 | $47.95 | $1.30 |
| **Medium** | 2 / 4 GiB / 20 GiB | $0.1620 | $116.64 | $2.59 |
| **Large** | 4 / 8 GiB / 50 GiB | $0.3258 | $234.58 | $6.48 |
| Organization ceiling | 4 / 32 GiB / 120 GiB | $0.6840 | $492.48 | $15.55 |

Two readings of that table matter.

**Per invocation, boxes are almost free.** A 30-second code-interpreter run on a Small box costs $0.00056 — ten thousand of them come to $5.55. Per-run cost is not where Cloud bills get large.

**Per month left running, they are not.** The gap between the last two columns is the whole cost story, and the next section is why it exists. [Cost controls](/cloud/cost-controls) is how you close it.

To make a box cheaper, cut vCPU first: one vCPU-hour costs as much as **3.5 GiB-hours of memory** or **280 GiB-hours of disk**. Trimming disk is not worth the thought — it is 2–3% of a running box.

## What each box state costs

| Box state | vCPU | Memory | Disk |
|---|---|---|---|
| **Running** | charged | charged | charged |
| **Stopped** | — | — | **charged** |
| Creating or starting | — | — | — |
| **Deleted** | — | — | — |

A stopped box has given back its compute but still occupies its disk, and it is billed for that disk until the box is deleted.

One forgotten box is loose change. A hundred of them is $130–$650 a month for nothing, and nothing clears them for you.

### How the hours are counted

Compute and disk are charged over different intervals. The two clocks start together and stop at different moments:

| Moment | vCPU + memory | Disk |
|---|---|---|
| Box created but never started | not charged | not charged |
| Box reaches **running** | clock starts | clock starts |
| You **request a stop** | **clock stops** | keeps running |
| Box is stopped, however long | not charged | keeps running |
| You **request deletion** | not charged | **clock stops** |

Two of those moments are earlier than you might expect, and both are in your favour:

- **Compute stops billing when the stop is requested**, not when the box has finished shutting down. You do not pay vCPU or memory for the shutdown itself.
- **Disk stops billing when deletion is requested**, not when teardown completes.

There is **no minimum billable duration and no rounding up to a whole hour**. The platform records the exact moment of each transition, so a box that runs for four minutes is charged for four minutes at the hourly rate. A box you create and never start costs nothing at all.

## Estimates and settlement

The **New Box** dialog quotes what your chosen size costs to run for one hour. Treat it as an estimate — your actual charge is settled from recorded usage, and the **Usage** tab is the authority on what you were charged. See [Managing billing](/cloud/billing#read-the-usage-chart).

## Troubleshooting

| Situation | Why it happens | What to do |
|---|---|---|
| A box you stopped days ago is still adding to your bill | A stopped box keeps its disk and is charged for it until deleted | Delete it, or set `auto_delete` so it clears itself. See [Cost controls](/cloud/cost-controls) |
| Cost is far higher than the size suggests | Something keeps the box busy, so it never goes idle and `auto_stop` never fires. A busy box is not an idle box | Check what is running inside it, or stop the box explicitly when the work finishes |
| Creation fails with `auto_delete must be greater than auto_stop` | Both are non-zero but `auto_delete` is not larger | Raise `auto_delete` above `auto_stop`, or set `auto_delete=0` to disable deletion |
| A request for more than 4 vCPU, 32 GiB of memory, or 120 GiB of disk is rejected | Those are per-box ceilings for the whole organization, enforced before the box is created | Lower the request or split the work across boxes. See [Per-box resource ceilings](/cloud/billing#per-box-resource-ceilings) |

## Next steps

<CardGroup cols={2}>
<Card title="Cost controls" icon="hand" href="/cloud/cost-controls">
The two lifecycle controls that stop a finished box from charging you.
</Card>
<Card title="Wallet or a plan?" icon="scale-balanced" href="/cloud/plans">
The usage level at which a subscription starts costing less.
</Card>
</CardGroup>
Loading
Loading