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

# Tools

> Tools exposed by the Bonya MCP server

The server registers 63 tools across 12 groups. Every tool takes and returns plain JSON — ids, not objects, are how you chain calls together (e.g. `sandbox_create` → its `sandbox_id` → `sandbox_exec`).

> [!NOTE]
>
> Results are returned as pretty-printed JSON text. Errors are returned as MCP tool errors (`isError: true`) formatted as `Bonya API error <status> (<code>): <detail>`, using the `code`/`detail` fields from the API's RFC 9457 problem+json error body.

## Sandboxes

Create and manage isolated compute environments.

### `sandbox_create`

Create a new sandbox (an isolated cloud compute environment) from a template. By default returns immediately with the sandbox in 'creating' state (202); pass wait=true to block until it is ready (201).

| Parameter | Type | Required | Description |
| - | - | - | - |
| `template_id` | string | no | Optional template id. Omit to use the deployment default. Use template\_list to discover available templates. |
| `template_version` | string | no | Optional specific template version. Defaults to the template's latest. |
| `name` | string | no | Optional display label (not unique; every lookup is by sandbox\_id). |
| `snapshot` | string | no | Optional snapshot id to restore the new sandbox from (see snapshot\_list). |
| `image` | string | no | Optional public OCI image reference (tag or digest) to create the sandbox from instead of a template. Cannot be combined with snapshot, template\_id or template\_version. Required for GPU sandboxes unless an image template is used. |
| `gpu` | object | no | Optional GPU request, for a GPU sandbox. Pick a type/count from sandbox\_gpu\_options (an empty list means no GPU capacity is available). Requires an `image` (or an image template); cannot be combined with snapshot or template\_version. Subject to the organization's concurrent-GPU limit. |
| `network` | object | no | Network egress policy for the sandbox. |
| `env` | object | no | Optional environment variables set in the sandbox. |
| `secret_sets` | string\[] | no | Optional secret set names to inject into the sandbox (see secret\_set\_list). |
| `wait` | boolean | no | If true, block until the sandbox is ready instead of returning immediately. |

### `sandbox_list`

List sandboxes, optionally filtered by state. Paginated.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `page_size` | integer | no | Page size (default 50). |
| `page_token` | string | no | Pagination token from a previous response. |
| `states` | `creating` \| `running` \| `warm` \| `cooling` \| `cold` \| `waking` \| `deleting` \| `failed` \| `lost`\[] | no | Filter to these states. Deleted sandboxes are not listed. |
| `include_disposable` | boolean | no | Include disposable (job-created) sandboxes in the listing. |

### `sandbox_get`

Fetch the current state of a single sandbox by id.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `sandbox_id` | string | yes | The sandbox id (e.g. as returned by sandbox\_create or sandbox\_list). |

### `sandbox_delete`

Permanently and synchronously delete a sandbox. Deleting an already-deleted sandbox succeeds (idempotent). This cannot be undone.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `sandbox_id` | string | yes | The sandbox id (e.g. as returned by sandbox\_create or sandbox\_list). |

## Lifecycle, network & GPU

Pause, keep awake (which also wakes a paused sandbox), restrict egress, fork, and see GPU capacity.

### `sandbox_pause`

Force a sandbox to pause. 'warm' keeps it quick to resume; 'cold' frees more resources but resumes slower. Returns once the stage is reached. A paused sandbox wakes on sandbox\_keepalive, on exec/file access, or on incoming traffic.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `sandbox_id` | string | yes | The sandbox id (e.g. as returned by sandbox\_create or sandbox\_list). |
| `stage` | `warm` \| `cold` | yes | Pause stage. |

### `sandbox_keepalive`

Place an expiring keep-awake hold on a sandbox so it is not auto-paused; a paused sandbox is woken. Returns keepalive\_until.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `sandbox_id` | string | yes | The sandbox id (e.g. as returned by sandbox\_create or sandbox\_list). |
| `for` | string | yes | Hold duration as a Go-style duration, e.g. "30m" or "2h". |

### `sandbox_network_update`

Replace the network egress policy of a running sandbox (open, allowlist of domains/CIDRs, or airgap).

| Parameter | Type | Required | Description |
| - | - | - | - |
| `sandbox_id` | string | yes | The sandbox id (e.g. as returned by sandbox\_create or sandbox\_list). |
| `mode` | `open` \| `allowlist` \| `airgap` | yes | open = unrestricted egress (default); allowlist = only the 'allow' destinations; airgap = no network. |
| `allow` | object\[] | no | Allowed destinations; used when mode is 'allowlist'. |

### `sandbox_gpu_options`

List the GPU type/count combinations currently available for GPU sandboxes (the 'gpu' parameter of sandbox\_create, which also needs an 'image'). An empty list means no GPU capacity is configured.

*No parameters.*

### `sandbox_fork`

Create N new sandboxes that start with the source sandbox's memory and disk, on the same node. Each child is a separate sandbox you must delete when done.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `sandbox_id` | string | yes | The sandbox id (e.g. as returned by sandbox\_create or sandbox\_list). |
| `count` | integer | yes | Number of forks to create. |

## Snapshots

Capture a sandbox's disk state and restore it with `sandbox_create`'s `snapshot` parameter.

### `snapshot_create`

Create a named snapshot of a sandbox that new sandboxes can later be restored from (sandbox\_create with 'snapshot').

| Parameter | Type | Required | Description |
| - | - | - | - |
| `sandbox_id` | string | yes | The sandbox id (e.g. as returned by sandbox\_create or sandbox\_list). |
| `name` | string | yes | Snapshot name. |

### `snapshot_list`

List the snapshots taken of a sandbox.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `sandbox_id` | string | yes | The sandbox id (e.g. as returned by sandbox\_create or sandbox\_list). |

### `snapshot_get`

Fetch a single snapshot by id.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `snapshot_id` | string | yes | The snapshot id (as returned by snapshot\_create or snapshot\_list). |

### `snapshot_delete`

Permanently delete a snapshot. This cannot be undone.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `snapshot_id` | string | yes | The snapshot id (as returned by snapshot\_create or snapshot\_list). |

## Exec & filesystem

Run buffered commands and work with files.

### `sandbox_exec`

Run a command in a sandbox and wait for it to finish (buffered, non-interactive). Returns exit code, stdout, and stderr. For long-running or interactive processes, use session\_create instead.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `sandbox_id` | string | yes | The sandbox id. |
| `cmd` | string\[] | yes | Command and arguments, e.g. \["bash","-lc","echo hi"] or \["ls","-la"]. |
| `path` | string | no | Working directory inside the sandbox. |
| `env` | object | no | Extra environment variables. |
| `timeout_s` | integer | no | Max seconds to wait for the command to finish (1-300). |
| `stdin_b64` | string | no | Base64-encoded bytes to write to the command's stdin. |
| `output_encoding` | `utf8` \| `base64` | no | Encoding for the returned stdout/stderr. Defaults to utf8. |

### `fs_read`

Read a file's raw bytes from a sandbox and return its UTF-8 text content.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `sandbox_id` | string | yes | The sandbox id. |
| `path` | string | yes | Path to read inside the sandbox. |

### `fs_write`

Write UTF-8 text content to a file in a sandbox, creating or overwriting it.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `sandbox_id` | string | yes | The sandbox id. |
| `path` | string | yes | Destination path inside the sandbox. |
| `content` | string | yes | UTF-8 text content to write. |

### `fs_list`

List the entries of a directory in a sandbox.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `sandbox_id` | string | yes | The sandbox id. |
| `path` | string | yes | Directory path inside the sandbox. |

### `fs_stat`

Get metadata (kind, size, mode, modified time) for a path in a sandbox.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `sandbox_id` | string | yes | The sandbox id. |
| `path` | string | yes | Path inside the sandbox. |

### `fs_mkdir`

Create a directory (and any missing parents) in a sandbox.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `sandbox_id` | string | yes | The sandbox id. |
| `path` | string | yes | Directory path to create inside the sandbox. |

### `fs_rename`

Rename or move a file or directory within a sandbox.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `sandbox_id` | string | yes | The sandbox id. |
| `from` | string | yes | Existing path inside the sandbox. |
| `to` | string | yes | New path inside the sandbox. |

### `fs_delete`

Delete a file or directory in a sandbox. Pass recursive=true to delete a non-empty directory.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `sandbox_id` | string | yes | The sandbox id. |
| `path` | string | yes | Path to delete inside the sandbox. |
| `recursive` | boolean | no | Delete directories recursively (default false). |

## Sessions

Long-lived named background processes.

### `session_create`

Create a named, long-lived session running a command in a sandbox. Unlike sandbox\_exec, the session keeps running in the background; use session\_list to check on it and session\_kill to stop it. Creating a session with a name that already has a live session fails with session\_exists (409) unless replace is set, which replaces a terminal (finished) session of the same name.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `sandbox_id` | string | yes | The sandbox id. |
| `name` | string | yes | The session name (unique per sandbox). |
| `cmd` | string\[] | yes | Command and arguments, e.g. \["bash","-lc","npm run dev"]. |
| `path` | string | no | Working directory inside the sandbox. |
| `env` | object | no | Extra environment variables. |
| `cols` | integer | no | Terminal columns. |
| `rows` | integer | no | Terminal rows. |
| `replace` | boolean | no | Replace an existing terminal (finished) session of the same name. |

### `session_list`

List sessions for a sandbox. Never wakes a suspended sandbox; a suspended sandbox answers from its suspend snapshot (sandbox\_suspended: true in the response).

| Parameter | Type | Required | Description |
| - | - | - | - |
| `sandbox_id` | string | yes | The sandbox id. |

### `session_kill`

Terminate a named session. Sends a signal (default TERM) and, after grace\_ms, escalates. Returns the session's resulting state.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `sandbox_id` | string | yes | The sandbox id. |
| `session_name` | string | yes | The session name (unique per sandbox). |
| `signal` | `TERM` \| `KILL` \| `INT` \| `HUP` | no | Signal to send (default TERM). |
| `grace_ms` | integer | no | Grace period before escalation in ms (default 5000, max 60000). |

## Previews

Publish a sandbox port at an HTTPS URL, with private (grant-token) or public access.

### `preview_create`

Create a preview URL that proxies to a port inside a sandbox, so a running service can be reached over the web. A 'private' preview (default) also returns a grant whose token and exchange\_url are shown only in this response; open exchange\_url once in a browser to get access. A 'public' preview needs no token.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `sandbox_id` | string | yes | The sandbox id. |
| `port` | integer | yes | Port inside the sandbox to expose. |
| `auth` | `private` \| `public` | no | 'private' (default) requires a grant token; 'public' is open. |
| `ttl_seconds` | integer | no | Grant lifetime in seconds (0 or omitted uses the service default). |

### `preview_list`

List all previews for a sandbox. Never returns grant tokens.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `sandbox_id` | string | yes | The sandbox id. |

### `preview_get`

Fetch a single preview by id.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `sandbox_id` | string | yes | The sandbox id. |
| `preview_id` | string | yes | The preview id (e.g. pv-...). |

### `preview_delete`

Delete a preview by id, immediately disabling its URL. Returns the deleted preview.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `sandbox_id` | string | yes | The sandbox id. |
| `preview_id` | string | yes | The preview id (e.g. pv-...). |

### `preview_grant_create`

Create a new access grant for a private preview. The token and exchange\_url are shown only in this response.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `sandbox_id` | string | yes | The sandbox id. |
| `preview_id` | string | yes | The preview id (e.g. pv-...). |
| `ttl_seconds` | integer | no | Grant lifetime in seconds (0 or omitted uses the service default). |

### `preview_grant_list`

List a preview's access grants. Tokens are never returned here.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `sandbox_id` | string | yes | The sandbox id. |
| `preview_id` | string | yes | The preview id (e.g. pv-...). |

### `preview_grant_renew`

Extend an access grant's lifetime.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `sandbox_id` | string | yes | The sandbox id. |
| `preview_id` | string | yes | The preview id (e.g. pv-...). |
| `grant_id` | string | yes | The grant id. |
| `ttl_seconds` | integer | no | Grant lifetime in seconds (0 or omitted uses the service default). |

### `preview_grant_revoke`

Revoke an access grant so its token stops working.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `sandbox_id` | string | yes | The sandbox id. |
| `preview_id` | string | yes | The preview id (e.g. pv-...). |
| `grant_id` | string | yes | The grant id. |

## Jobs

Managed one-off runs of a command or script.

### `job_create`

Run or start a job on a new or existing sandbox. wait=false (default) starts durably and returns run\_id immediately (202); wait=true blocks for the result, bounded by the caller's own request timeout (200).

| Parameter | Type | Required | Description |
| - | - | - | - |
| `job` | object | yes | Exactly one of existing\_sandbox\_id/new\_sandbox is required, and exactly one of cmd/script is required. |

### `job_list`

List a tenant's job runs, newest first. Paginated; optionally filtered by sandbox or schedule.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `sandbox_id` | string | no | Filter to runs on this sandbox. |
| `schedule_id` | string | no | Filter to runs fired by this schedule. |
| `page_size` | integer | no | Page size. |
| `page_token` | string | no | Pagination token from a previous response. |

### `job_get`

Full run detail: status, result, and an activity timeline, plus the stored job spec that started it. Since there is no endpoint to edit a run in place, to 'edit and rerun' a run: call job\_get, modify the returned job object, and pass it to job\_create as a new run.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `run_id` | string | yes | The job run id (e.g. as returned by job\_create or job\_list). |

### `job_cancel`

Request cancellation of a running job. This cancels rather than terminates, so the run's own cleanup (e.g. deleting a sandbox it created) still executes.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `run_id` | string | yes | The job run id (e.g. as returned by job\_create or job\_list). |

## Job schedules

Cron, interval or one-shot triggers for a job.

### `job_schedule_create`

Create a durable cron, interval, or one-shot trigger for a job. Exactly one of cron\_expressions/interval\_s/run\_at\_unix\_nanos is required. A one-shot schedule is run\_at\_unix\_nanos set (refused if in the past), not a separate mechanism.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `cron_expressions` | string\[] | no | Cron expressions to fire on. |
| `interval_s` | integer | no | Fire every N seconds. |
| `run_at_unix_nanos` | number | no | One-shot: a single future calendar time (unix nanos). Refused if in the past. |
| `time_zone` | string | no | IANA zone, e.g. US/Pacific. Empty is UTC. |
| `jitter_s` | integer | no | Random delay added to each fire, in seconds. |
| `overlap` | `skip` \| `buffer_one` \| `allow_all` | no | What a fire does when the previous run is still going (default 'skip', which drops the new fire). |
| `paused` | boolean | no | Create the schedule already paused (default false). |
| `job` | object | yes | Exactly one of existing\_sandbox\_id/new\_sandbox is required, and exactly one of cmd/script is required. |

### `job_schedule_list`

List a tenant's job schedules. Paginated.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `page_size` | integer | no | Page size. |
| `page_token` | string | no | Pagination token from a previous response. |

### `job_schedule_get`

Fetch a job schedule, including its timing, stored job spec, pause state, next run time, and recent/running run ids.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `schedule_id` | string | yes | The job schedule id (e.g. as returned by job\_schedule\_create or job\_schedule\_list). |

### `job_schedule_update`

Replace a job schedule's timing and/or job spec. Same body shape and same-field requirements as job\_schedule\_create (exactly one of cron\_expressions/interval\_s/run\_at\_unix\_nanos).

| Parameter | Type | Required | Description |
| - | - | - | - |
| `schedule_id` | string | yes | The job schedule id (e.g. as returned by job\_schedule\_create or job\_schedule\_list). |
| `cron_expressions` | string\[] | no | Cron expressions to fire on. |
| `interval_s` | integer | no | Fire every N seconds. |
| `run_at_unix_nanos` | number | no | One-shot: a single future calendar time (unix nanos). Refused if in the past. |
| `time_zone` | string | no | IANA zone, e.g. US/Pacific. Empty is UTC. |
| `jitter_s` | integer | no | Random delay added to each fire, in seconds. |
| `overlap` | `skip` \| `buffer_one` \| `allow_all` | no | What a fire does when the previous run is still going (default 'skip', which drops the new fire). |
| `paused` | boolean | no | Whether the schedule is paused. |
| `job` | object | yes | Exactly one of existing\_sandbox\_id/new\_sandbox is required, and exactly one of cmd/script is required. |

### `job_schedule_delete`

Permanently delete a job schedule. Does not cancel any run currently in flight.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `schedule_id` | string | yes | The job schedule id (e.g. as returned by job\_schedule\_create or job\_schedule\_list). |

### `job_schedule_pause`

Set a job schedule's paused state.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `schedule_id` | string | yes | The job schedule id (e.g. as returned by job\_schedule\_create or job\_schedule\_list). |
| `paused` | boolean | yes | true to pause, false to resume. |
| `note` | string | no | Optional note recorded alongside the pause/resume. |

### `job_schedule_trigger`

Fire one run of a job schedule immediately, overriding the schedule's own timing.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `schedule_id` | string | yes | The job schedule id (e.g. as returned by job\_schedule\_create or job\_schedule\_list). |

## Templates

Saved, versioned launch configurations.

### `template_list`

List the organization's saved templates (launch configurations), each at its latest revision. Use a template's id as sandbox\_create's template\_id.

*No parameters.*

### `template_get`

Fetch a template, optionally at a specific revision (default: latest).

| Parameter | Type | Required | Description |
| - | - | - | - |
| `template_id` | string | yes | The template id. |
| `revision` | integer | no | |

### `template_create`

Create a template from an image and settings. The image is resolved and validated on save; the template starts at revision 1.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `name` | string | yes | Template name (unique per organization). |
| `description` | string | no | |
| `config` | object | yes | Template launch configuration. The service resolves the image to a digest and pins secret set revisions on save. |

### `template_update`

Update a template. Omitted fields keep their value. Changing config publishes a new immutable revision; pass revision (the current one) to guard against concurrent edits.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `template_id` | string | yes | The template id. |
| `name` | string | no | |
| `description` | string | no | |
| `config` | object | no | Template launch configuration. The service resolves the image to a digest and pins secret set revisions on save. |
| `revision` | integer | no | Expected current revision. |

### `template_delete`

Permanently delete a template. Existing sandboxes are not affected.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `template_id` | string | yes | The template id. |

## Registry connections

Credentials for pulling private images. Passwords are write-only.

### `registry_connection_list`

List stored credentials for pulling private container images. Passwords are never returned.

*No parameters.*

### `registry_connection_create`

Store credentials for a private container registry. The password is write-only.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `name` | string | yes | |
| `registry` | string | yes | Registry host, e.g. ghcr.io. |
| `username` | string | yes | |
| `password` | string | yes | Password or access token (write-only). |

### `registry_connection_update`

Replace a registry connection's name, host, username and password.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `connection_id` | string | yes | The registry connection id. |
| `name` | string | yes | |
| `registry` | string | yes | |
| `username` | string | yes | |
| `password` | string | yes | Password or access token (write-only). |

### `registry_connection_delete`

Delete a registry connection. Fails if a template still uses it.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `connection_id` | string | yes | The registry connection id. |

### `registry_connection_validate`

Resolve an image through a registry connection and return its digest.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `connection_id` | string | yes | The registry connection id. |
| `image` | string | yes | Image reference to resolve. |

## Secrets & secret sets

Write-only secrets and named groups of environment variables. Reference secret sets by **name**.

### `secret_list`

List secrets (names and timestamps only; values are write-only and never returned).

*No parameters.*

### `secret_create`

Store a write-only secret, bindable to an environment variable in a template (secret\_bindings).

| Parameter | Type | Required | Description |
| - | - | - | - |
| `name` | string | yes | |
| `value` | string | yes | The secret value (write-only). |

### `secret_update`

Replace a secret's name and value.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `secret_id` | string | yes | The secret id. |
| `name` | string | yes | |
| `value` | string | yes | New value (write-only). |

### `secret_delete`

Delete a secret. Fails if a template still binds it.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `secret_id` | string | yes | The secret id. |

### `secret_set_list`

List secret sets: named groups of environment variables you can inject into sandboxes and jobs via secret\_sets. Key names are returned, never values.

*No parameters.*

### `secret_set_get`

Fetch a secret set (key names and revision; no values).

| Parameter | Type | Required | Description |
| - | - | - | - |
| `secret_set_id` | string | yes | The secret set id. |

### `secret_set_create`

Create a secret set from environment variable names and values (values are write-only).

| Parameter | Type | Required | Description |
| - | - | - | - |
| `name` | string | yes | |
| `values` | object | yes | Environment variable name -> value (write-only). |

### `secret_set_update`

Update a secret set; publishes a new revision. Pass revision (the current one) to guard against concurrent edits.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `secret_set_id` | string | yes | The secret set id. |
| `name` | string | no | |
| `values` | object | no | Replacement values (write-only). |
| `revision` | integer | no | Expected current revision. |

### `secret_set_delete`

Delete a secret set. Fails if a template still references it.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `secret_set_id` | string | yes | The secret set id. |

## Organizations

The organizations your key belongs to; use an id as `BONYA_ORGANIZATION_ID`.

### `organization_list`

List the organizations the API key's user belongs to, with your role in each. Use an organization\_id as BONYA\_ORGANIZATION\_ID to scope this server to it.

*No parameters.*

## Not exposed as tools

> [!NOTE]
>
> The API's WebSocket endpoints (TTY `exec` and session `attach`) are not exposed as tools — they don't fit a request/response MCP tool. `sandbox_exec` covers non-interactive commands through the buffered `POST .../exec` endpoint, and `session_create` covers long-running background processes. Identity management (creating organizations, members, invites and API keys) is not available to API keys and is not exposed.

## Gotchas

* **Sandbox capacity is capped per account.** If `sandbox_create` or `job_create`'s `new_sandbox` path returns `429 rate_limited`, free a slot with `sandbox_delete` or wait for a job-created sandbox to finish rather than retrying immediately.
* **`session_kill`'s parameter is `session_name`**, not `name` — easy to get wrong since `session_create` takes `name`.
* **A job's `disposition` only applies to a sandbox the job itself created.** The default is `delete`, so a job-created sandbox disappears once the run ends, however it ends (including on `job_cancel`).
* **Secret sets are referenced by name**, not id, in `secret_sets` on templates, sandboxes and jobs.
* **GPU sandboxes** need an `image` (or an image template) and available org GPU quota; check `sandbox_gpu_options`.
* **Preview grant tokens are shown once**, in the response that creates them.
* **Errors are RFC 9457 `problem+json`**, surfaced as `Bonya API error <status> (<code>): <message>`. The `code` is the stable machine-readable part.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.