Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
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
6 changes: 5 additions & 1 deletion docs/api-coverage.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,9 @@
Based on the resource OpenAPI document from `../platform` at `f20ded3`, plus its dashboard
auth integrations. The `query` filter on `GET /v1/sandboxes` and the `name` and `status`
filters on `GET /v1/images` come from platform `2396647`. `GET /v1/sandboxes/{id}/usage`
comes from platform `d3b6c77`. The model routes come from platform `8747699`.
comes from platform `d3b6c77`. `GET /v1/usage` and `GET /v1/usage/summary` come from
platform `8af1e3e`, and their model usage from `1ae5640`. The model catalog and provider
routes come from platform `8747699`.
Every resource operation has a named command, except model provider writes (`POST`, `PUT`,
and `DELETE` on `/v1/model-gateway/providers`); configure providers in the Platform dashboard.
`adapt api METHOD PATH` also exposes same-origin JSON requests for less common account operations.
Expand All @@ -23,6 +25,8 @@ one from the CLI, or reuse the UUID supplied with `--idempotency-key`.
| `GET /v1/sandboxes` | `sandbox list [--query TEXT]` |
| `GET /v1/sandboxes/{id}` | `sandbox get ID` |
| `GET /v1/sandboxes/{id}/usage` | `sandbox usage ID [--hours 1\|24]` |
| `GET /v1/usage` | `usage list [--kind sandbox\|model] [--days 7\|30\|90] [--user ID] [--sandbox ID]` |
| `GET /v1/usage/summary` | `usage summary [--kind sandbox\|model] [--days 7\|30\|90] [--user ID]` |
| `DELETE /v1/sandboxes/{id}` | `sandbox delete ID` |
| `POST /v1/sandboxes/{id}/start` | `sandbox start ID` |
| `POST /v1/sandboxes/{id}/stop` | `sandbox stop ID` |
Expand Down
37 changes: 37 additions & 0 deletions docs/cli-reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -47,6 +47,7 @@ For example, use `adapt org members ls` or `adapt sandbox ls --all`.
| `keys` | `list`, `create`, `delete` |
| `sessions` | `list`, `revoke`, `revoke-others` |
| `mcp` | `list`, `revoke`, `tools` |
| `usage` | `list`, `summary` |
| `events` | Show organization changes, or personal changes with `--personal` |
| `health` | Test API availability, or database readiness with `--ready` |
| `profiles` | Show saved API URLs, organizations, and credential status |
Expand Down Expand Up @@ -244,6 +245,7 @@ Shows measured CPU and resident memory for the last hour (default) or 24 hours.
Each can be shorter than the requested window, and memory coverage can differ from CPU coverage.
For example, one hour of CPU data and six minutes of memory data show `1h of 1h` and `6m of 1h`, respectively.
A dash means nothing was measured, not zero usage.
Totals under 0.01 hours show in seconds, for example `19.5 CPU-s`, so short runs don't round to zero.
A note under the table counts intervals that Platform estimated from allocated resources instead of measuring.
Use `--json` for the exact Platform totals and chart points.

Expand Down Expand Up @@ -392,6 +394,40 @@ Create a sandbox with the image and variable set:
adapt sandbox create --image-id IMAGE_ID --variable-set VARIABLE_SET_ID --wait
```

## Metered usage

```sh
adapt usage list
adapt usage list --kind model --days 7
adapt usage list --sandbox SANDBOX_ID --all --json
adapt usage summary
adapt usage summary --kind model --days 90 --user USER_ID
```

These commands show metered sandbox runs and model calls.
They are not an audit log of user activity.
Members see only their own usage.
Owners, admins, and API keys see the whole organization and can select one member with `--user`.

`usage list` shows records newest first, one row per sandbox run or model call.
For sandbox runs, a note under the table counts intervals in the displayed records that Platform estimated from allocated resources instead of measuring.
Use `--kind model` for model calls; the default is `sandbox`.
`--days` accepts `7`, `30`, or `90` and counts UTC days, including today.
Without `--days`, the list includes all history.
Sandbox runs count if they finished in that time or are still running.
`--sandbox` accepts a full UUID or an unambiguous ID prefix, and only works with sandbox usage.
Full UUIDs can filter historical events for deleted sandboxes; only prefixes require a non-deleted sandbox.

`usage summary` totals usage per member over the last 30 UTC days, or over `--days`.
The table adds a total row.
A dash means nothing was measured, not zero usage.
As with `sandbox usage`, totals under 0.01 hours show in seconds.
Notes under the table count intervals that Platform estimated from allocated resources, and model calls that reported no token counts.
Model token totals include calls made with your organization's own provider keys.
To separate them, use `usage list --kind model --json` and check each call's `details.credentialSource`.

Use `--json` for exact totals, daily rows, and per-model breakdowns.

## Models

List the models enabled in your organization:
Expand Down Expand Up @@ -501,6 +537,7 @@ adapt sandbox list --limit 50 --cursor CURSOR
adapt sandbox list --query web --all --json
adapt images list --status ready
adapt images list --name ubuntu --all
adapt usage list --kind model --days 30 --all --json
```

`sandbox list --query TEXT` matches names that contain TEXT, without case sensitivity.
Expand Down
5 changes: 4 additions & 1 deletion skills/adapt/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,8 @@
name: adapt
description: >-
Use the adapt CLI to manage Adapt Platform sandboxes, run remote commands,
transfer files, and discover or execute tools from connected MCP servers.
transfer files, check metered usage, and discover or execute tools from
connected MCP servers.
Use when the user asks to work with Platform resources or their connected tools.
---

Expand Down Expand Up @@ -52,6 +53,8 @@ adapt sandbox sh --image ubuntu:24.04 -- uname -a
adapt sandbox sh --image-id IMAGE_ID --cpu 2 --memory 2048 -- /bin/sh -lc 'echo hello; uname -a'
adapt sandbox create --image-id IMAGE_ID --wait
adapt sandbox usage SANDBOX_ID --hours 24 --json
adapt usage summary --kind model --days 7 --json
adapt usage list --kind sandbox --days 30 --all --json
adapt exec SANDBOX_ID --cwd /app -- /bin/sh -lc 'npm test'
```

Expand Down
62 changes: 62 additions & 0 deletions src/cli.rs
Original file line number Diff line number Diff line change
Expand Up @@ -87,6 +87,9 @@ pub enum Command {
/// Inspect connected MCP clients and the tools the Platform MCP server provides
#[command(subcommand)]
Mcp(McpCommand),
/// Show metered sandbox and model usage (not an audit log)
#[command(subcommand)]
Usage(UsageCommand),
/// Watch resource changes as newline-delimited JSON
Events {
#[arg(long)]
Expand Down Expand Up @@ -728,6 +731,65 @@ pub enum SessionCommand {
RevokeOthers,
}

#[derive(Subcommand)]
#[command(
after_help = "This is metered usage, not an audit log.\nMembers see only their own usage; owners, admins, and API keys see the whole organization."
)]
pub enum UsageCommand {
/// List metered sandbox runs or model calls, newest first
#[command(
visible_alias = "ls",
after_help = "This is metered usage, not an audit log."
)]
List(UsageList),
/// Total metered usage per member over the last 7, 30, or 90 UTC days
#[command(
after_help = "This is metered usage, not an audit log.\nModel token totals include calls made with your organization's own provider keys.\nTo separate them, use `usage list --kind model --json` and check each call's details.credentialSource."
)]
Summary(UsageSummary),
}

#[derive(Args)]
pub struct UsageScope {
/// Kind of usage
#[arg(long, value_enum, default_value = "sandbox")]
pub kind: UsageKind,
/// Show one member's usage (owners, admins, and API keys only)
#[arg(long, value_name = "USER_ID")]
pub user: Option<Uuid>,
}

#[derive(Clone, Copy, ValueEnum)]
pub enum UsageKind {
Sandbox,
Model,
}

#[derive(Args)]
pub struct UsageList {
#[command(flatten)]
pub scope: UsageScope,
/// Limit to the last N UTC days, including today; omit for all history.
/// Sandbox runs count if they finished in that time or are still running
#[arg(long, value_parser = ["7", "30", "90"])]
pub days: Option<String>,
/// Show runs of one sandbox (full UUID or unambiguous ID prefix).
/// Full UUIDs include deleted-sandbox history; prefixes require a non-deleted sandbox
#[arg(long)]
pub sandbox: Option<ResourceRef>,
#[command(flatten)]
pub page: Page,
}

#[derive(Args)]
pub struct UsageSummary {
#[command(flatten)]
pub scope: UsageScope,
/// Number of UTC days to total, including today
#[arg(long, default_value = "30", value_parser = ["7", "30", "90"])]
pub days: String,
}

#[derive(Subcommand)]
pub enum ModelCommand {
/// List the organization's enabled models, as provider/model IDs
Expand Down
Loading
Loading