# Billing and usage

caas.sh is prepaid. Each workspace has a balance that you top up with a card. Usage is deducted from it as it's recorded. There's no subscription fee, no minimum and no monthly invoice. Each successful top-up gets its own Stripe receipt.

This guide covers the balance, adding funds, auto-recharge, what happens when the balance runs out, what each meter costs, and how to read your usage.

## How billing works

- **One balance per workspace.** Sandboxes, MCP servers, workflow runs and registry images all draw from the balance of the workspace they belong to.
- **Usage is deducted as it's recorded.** caas.sh charges the balance to the millionth of a dollar and never rounds up to cents.
- **Sandboxes need a card and funds.** A sandbox can start only while the workspace has a card on file and a balance above $0. Adding funds for the first time saves your card.
- **Prices are in US dollars.** The rates are listed under [Rates](#rates) and on the [pricing page](/pricing.html).

Who can do what depends on your role in the workspace:

| Role | Billing access |
| --- | --- |
| Owner | Sees usage and the balance, adds funds, changes auto-recharge, the spend alert and the card |
| Viewer | Sees usage and the balance, and downloads the usage CSV |
| Operator | No billing access |

## Add funds

1. In the [console](https://console.caas.sh/), open **Usage & billing**.
2. In the **Auto-recharge** section, enter an **Amount** from $5 to $2,000, such as `25` or `$25.50`.
3. Choose **Add funds**.

What happens next depends on whether the workspace has a card on file:

- **No card yet:** Stripe Checkout opens. Paying there adds the funds and saves your card for later top-ups.
- **Card on file:** caas.sh charges that card. The top-up shows as **Processing** under **Recent top-ups**, and the balance updates once Stripe confirms the payment. If your bank asks you to verify the payment, Stripe Checkout opens so you can finish it there.

If the card is declined, the page shows Stripe's reason, and the top-up is listed as **Failed**. Try another card (see [Receipts and payment methods](#receipts-and-payment-methods)) or another amount.

From a terminal:

```sh
caas billing add-funds 25
```

With a card on file, this charges it. Otherwise it prints a Stripe Checkout link, which you open to pay and save your card. See [Billing from the CLI and the API](#billing-from-the-cli-and-the-api) for the API key it needs.

## Auto-recharge

Auto-recharge keeps the balance from running out by charging your card when the balance gets low. **It's off by default.** Saving a card or adding funds never turns it on.

To turn it on:

1. Open **Usage & billing** and find the **Auto-recharge** section.
2. Set **Auto-recharge** to **On**.
3. Set **When balance falls below**, the minimum: $5 to $1,000. The default is $10.
4. Set **Recharge to**, the target: at least $5 above the minimum, and at most $2,000. The default is $50.
5. Choose **Save**.

Auto-recharge needs a card on file. If you turn it on before there's one, it starts working once a card is saved, for example by your first top-up.

### How a recharge works

- When usage takes the balance below the minimum, caas.sh charges your card once to bring the balance back to the target. It charges the target minus the balance, rounded up to the cent. For example, with a $10 minimum and a $50 target, a balance of $9.40 gets a $40.60 charge.
- It charges once each time the balance falls below the minimum. It doesn't charge again until the balance is back at or above the minimum.
- It also recharges at once if the balance is below the minimum when you turn auto-recharge on, when you raise the minimum above a balance that was at or above the old minimum, or when a new card is saved, unless a recharge is already on its way.
- Each recharge is listed under **Recent top-ups** as **Auto-recharge**, with its receipt.

### If a recharge is declined

The **Auto-recharge** section shows the decline with Stripe's reason, and caas.sh sends one email about it. It tries again an hour later, then six hours after that, then a day after that: four attempts in all, each charging whatever then brings the balance to the target. Each attempt charges the card on file at the time, so a card you change in the meantime is the one the next attempt charges. After the last attempt, saving a new card recharges at once if the balance is still below the minimum. You can also add funds yourself at any time; once the balance is back at the minimum, the remaining attempts are canceled.

### While auto-recharge is off

caas.sh emails a low-balance warning each time the balance falls below the **When balance falls below** amount. Nothing is charged. Sandboxes stop when the balance reaches $0. The same warning goes out while auto-recharge is on but no card is on file.

Low-balance warnings and declined-recharge emails go to the billing email Stripe has for the workspace, which starts as the email of the owner who first added funds or a card in the console. If Stripe has no email, they go to the owner who set the spend alert.

From a terminal:

```sh
caas billing auto-recharge show
caas billing auto-recharge set --below 10 --recharge-to 50
caas billing auto-recharge set --off
```

`set` turns auto-recharge on and keeps any amount you don't give. `--off` turns it off.

## When the balance reaches $0

When the balance reaches $0 or goes below it:

- Every running sandbox and MCP server stops, saving its state the same way an [idle stop](/docs/sandboxes#idle-stop) does.
- Workflow runs that are queued, running or paused fail, with the reason "The workspace ran out of funds while the run ran". You can resume them once you've added funds. See [Resume a failed run](/docs/workflows#resume-a-failed-run).
- Starting a sandbox or a workflow run is refused, and so is resuming a run. The console says the balance is empty, and the API answers `402` with the code `out_of_funds`.
- Storage keeps billing: snapshots, carried files and registry images. Together with usage recorded just before the stop, this can take the balance below $0.

To run again, add enough funds to bring the balance above $0, then start your sandboxes and resume your runs. As after an idle stop, a sandbox stopped this way also starts again by itself when a command, a file transfer or a request to its URL arrives. On the **Usage & billing** page, a balance at or below $0 is shown in red.

Without a card on file, sandboxes can't start whatever the balance. The API answers `402` with the code `payment_method_required`.

## Rates

Sandboxes bill per resource, MCP servers per request on top of their sandbox, workflows per step on top of their sandboxes, and the registry for storage, pulls and lists.

### Sandboxes

| Meter | Price | What counts |
| --- | --- | --- |
| Active vCPU | $0.15 / vCPU-hour | CPU time the sandbox uses, only while it computes. A running sandbox that's waiting uses none. |
| Memory | $0.018 / GiB-hour | The memory of the sandbox's size, while it runs |
| Disk | $0.001 / GB-hour | The disk of the sandbox's size, while it runs |
| Egress | $0.06 / GB | Data leaving the sandbox: what it sends to the internet, and what you download from it through its MCP endpoint, its URL, its files and its command output. Pulls of your images from registry.caas.sh don't count. |
| Snapshot storage | $0.025 / GB-month | Each snapshot, from when it's taken until it's deleted |
| Snapshot create and restore | Included | No charge per operation |

A stopped sandbox bills no vCPU, memory or disk, only its snapshots. See [Sizes](/docs/sandboxes#sizes) for each size's vCPU, memory and disk.

### MCP servers

| Meter | Price | What counts |
| --- | --- | --- |
| MCP Gateway requests | $0.005 / 1,000 requests | Requests to the server's endpoint with a valid client token |

Requests refused for a missing, invalid, expired or revoked token aren't billed. The server runs in a sandbox, which bills at the sandbox rates while it runs. See [MCP servers](/docs/mcp).

### Workflows

| Meter | Price | What counts |
| --- | --- | --- |
| Workflow steps | $1.00 / 1,000 steps | Each time a step starts, so $0.001 a step |
| Carried files | $0.10 / GiB-month | The outputs steps hand on to later steps, kept while the run is active and for 7 days after it ends |
| Checkpoints and resumes | Included | No charge per checkpoint or resume |

Each step's sandbox also bills at the sandbox rates for the time it runs, including its egress. A sandbox declared under `sandboxes` in the workflow file (see [Share a sandbox between steps](/docs/workflows#share-a-sandbox-between-steps)) keeps a checkpoint of its workspace, which bills as snapshot storage for as long as the carried files are kept. A resumed run pays only for the steps it runs again. See [Workflows](/docs/workflows).

### Container registry

| Meter | Price | What counts |
| --- | --- | --- |
| Registry storage | $0.025 / GB-month | The images you keep at registry.caas.sh |
| Registry pulls | $0.01 / 1,000 pulls | Each image manifest fetched, by Docker or by your sandboxes. A multi-platform image counts two: its index and the platform's manifest. `HEAD` requests and layer downloads are free. |
| Registry lists | $0.005 / 1,000 lists | Each listing of an image's tags (`tags/list`). The registry doesn't list your workspace's image names. |

See [Images and the registry](/docs/images).

### Units and rounding

- A month is 30 days (720 hours) for every per-month price.
- A GB is 1,000,000,000 bytes, for disk, egress, snapshot storage and registry storage. A GiB is 1,073,741,824 bytes, for memory and carried files.
- Each meter's amount is rounded down to the millionth of a dollar.
- Top-ups are whole cents.

### Example: an M sandbox for one hour

An M sandbox has 1/2 vCPU, 4 GiB of memory and 8 GB of disk. Say it runs for one hour and uses 6 minutes of CPU time, which is 0.1 vCPU-hours:

| Line | Calculation | Cost |
| --- | --- | --- |
| Active vCPU | 0.1 × $0.15 | $0.015 |
| Memory | 4 × $0.018 | $0.072 |
| Disk | 8 × $0.001 | $0.008 |
| **Total** | | **$0.095** |

Egress and snapshots are billed on top.

## The Usage & billing page

Open **Usage & billing** in the console to see a month's spend. The menu at the top switches between this month and last month. Months and days are in UTC.

- **Summary:** **Month to date**, **Projected for** the month (see [Projections](#projections)), and **Today so far**. For last month, you see the month's total instead.
- **Daily spend:** one bar per day, with today's bar marked.
- **By meter, month to date:** each meter's usage, rate, share of the total and cost, then the **Total**. Storage meters show the average amount stored over the period. Snapshot create and restore are listed as included.
- **Spend alert** and **Auto-recharge:** see [Spend alerts](#spend-alerts) and [Auto-recharge](#auto-recharge).

The **Spend this month** tile on the **Overview** shows the same month-to-date total.

### Download usage as CSV

Choose **Download CSV** to save the selected month as `caas-usage-YYYY-MM.csv`. It has one row per day and meter with usage, and its amounts add up exactly to the **By meter** table and the month's total.

| Column | Contents |
| --- | --- |
| `day` | The UTC day, such as `2026-10-07` |
| `meter` | The meter: `vcpu`, `memory`, `disk`, `egress`, `snapshotStorage`, `gatewayRequests`, `workflowSteps`, `carriedFiles`, `registryStorage`, `registryPulls`, `registryLists`, or `snapshotOperations` for the included snapshot creates and restores |
| `quantity` | The usage, in the unit the price is quoted in |
| `unit` | That unit: `vcpu-hour`, `gib-hour`, `gb-hour`, `gb`, `gb-month`, `1000-requests`, `1000-steps`, `gib-month`, `1000-pulls`, `1000-lists`, or `operation` |
| `rate_usd` | The price per unit, in dollars with six decimal places |
| `amount_usd` | What the row cost, in dollars with six decimal places |

Snapshot operations have a rate and amount of `0.000000`. From a terminal, `caas billing usage --csv` prints the same file:

```sh
caas billing usage --month 2026-09 --csv > caas-usage-2026-09.csv
```

## Spend alerts

A spend alert emails you the first time a month's spend reaches an amount you choose. It doesn't stop or limit anything.

1. Open **Usage & billing**.
2. In **Spend alert**, enter an amount in dollars, such as `300`. The field is labeled with the current month, such as **Email me when October passes**.
3. Choose **Save**.

Only owners can set it. The email goes to the owner who saved the alert. The amount applies to every month until you change it, and each amount emails at most once a month. If you set a new amount after an alert, the new amount can alert again in the same month. To turn the alert off, clear the amount and choose **Save**.

### Projections

For the current month, caas.sh projects the month's spend at the current pace: the month to date, divided by the days so far (today counts as a whole day), times the days in the month. The summary shows it as **Projected for** the month, and the spend alert shows when you'd reach your amount at that pace, such as "At the current pace you'd reach $300 around Oct 23."

## Receipts and payment methods

caas.sh doesn't send monthly invoices. Each top-up that succeeds, whether you added the funds or auto-recharge did, gets a Stripe receipt:

- On **Usage & billing**, **Recent top-ups** lists your latest top-ups, each paid one with a **Receipt** link.
- In **Settings**, the **Billing** section, which only owners see, lists receipts for recent top-ups.
- `caas billing balance` prints recent top-ups with their receipt links.

Owners manage the card:

- **Change** next to the card on **Usage & billing**, or **Manage billing** in **Settings**, opens Stripe's billing portal, where you manage your card.
- **Add payment method** in **Settings** saves a card through Stripe Checkout without charging it.

Top-ups and auto-recharge charge the card marked **(charged)** in **Settings**.

## Billing from the CLI and the API

The CLI and the API need an API key with billing access. In the console, an owner opens **Settings**, enters a **Key name** in the **API keys** card, checks **Billing access**, and chooses **Create key**. See [Connect the CLI to your workspace](/docs/cli#connect-the-cli-to-your-workspace) to configure the CLI with it.

```sh
caas billing balance
caas billing usage
caas billing usage --month 2026-09
caas billing add-funds 25
caas billing auto-recharge set --below 10 --recharge-to 50
```

`caas billing balance` prints the balance, the auto-recharge setting and recent top-ups. `caas billing usage` prints a month's spend by meter, the projection while the month is current, and the spend alert. Add `--json` to any of them to get the response as JSON. See [Billing](/docs/cli#billing) in the CLI guide for every option.

The API serves the same data under `https://api.caas.sh/v1/tenants/<tenant-id>/billing/`, where `<tenant-id>` is the **Tenant ID** in **Settings**:

| Request | What it does |
| --- | --- |
| `GET …/billing/balance` | The balance, auto-recharge, the card and recent top-ups |
| `GET …/billing/usage?month=YYYY-MM` | A month's usage report, this month by default. Add `&format=csv` for the CSV. |
| `POST …/billing/top-ups` | Adds funds: `{"amountMicroUsd": 25000000}` for $25, with an `Idempotency-Key` header of 8 to 128 characters. Without a card on file, the response has a Stripe Checkout `url` to pay at. |
| `GET …/billing/auto-recharge` | The auto-recharge setting |
| `PUT …/billing/auto-recharge` | Changes any of `enabled`, `minimumMicroUsd` and `targetMicroUsd` |

Amounts are in millionths of a dollar. Reading needs the `billing:read` scope, and adding funds or changing auto-recharge needs `billing:write`; a key created with **Billing access** has both. For example:

```sh
curl "https://api.caas.sh/v1/tenants/$CAAS_TENANT/billing/usage?month=2026-10&format=csv" \
  -H "Authorization: Bearer $CAAS_API_KEY"
```

See [Send the key](/docs/api#send-the-key) for setting `CAAS_TENANT` and `CAAS_API_KEY`, and [Billing](/docs/api#billing) in the API guide for the response fields.