Tools

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).

​

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).

​

sandbox_list

List sandboxes, optionally filtered by state. Paginated.

​

sandbox_get

Fetch the current state of a single sandbox by id.

​

sandbox_delete

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

​

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.

​

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.

​

sandbox_network_update

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

​

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.

​

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’).

​

snapshot_list

List the snapshots taken of a sandbox.

​

snapshot_get

Fetch a single snapshot by id.

​

snapshot_delete

Permanently delete a snapshot. This cannot be undone.

​

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.

​

fs_read

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

​

fs_write

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

​

fs_list

List the entries of a directory in a sandbox.

​

fs_stat

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

​

fs_mkdir

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

​

fs_rename

Rename or move a file or directory within a sandbox.

​

fs_delete

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

​

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.

​

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).

​

session_kill

Terminate a named session. Sends a signal (default TERM) and, after grace_ms, escalates. Returns the session’s resulting state.

​

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.

​

preview_list

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

​

preview_get

Fetch a single preview by id.

​

preview_delete

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

​

preview_grant_create

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

​

preview_grant_list

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

​

preview_grant_renew

Extend an access grant’s lifetime.

​

preview_grant_revoke

Revoke an access grant so its token stops working.

​

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).

​

job_list

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

​

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.

​

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.

​

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.

​

job_schedule_list

List a tenant’s job schedules. Paginated.

​

job_schedule_get

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

​

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).

​

job_schedule_delete

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

​

job_schedule_pause

Set a job schedule’s paused state.

​

job_schedule_trigger

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

​

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).

​

template_create

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

​

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.

​

template_delete

Permanently delete a template. Existing sandboxes are not affected.

​

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.

​

registry_connection_update

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

​

registry_connection_delete

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

​

registry_connection_validate

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

​

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).

​

secret_update

Replace a secret’s name and value.

​

secret_delete

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

​

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).

​

secret_set_create

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

​

secret_set_update

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

​

secret_set_delete

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

​

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

​

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.