# Bonya

- [Introduction](https://docs.bonya.ai/index.md): Welcome to the Bonya documentation
- [Quickstart](https://docs.bonya.ai/quickstart.md): Create a sandbox and run a command in under 5 minutes
- [Authentication](https://docs.bonya.ai/authentication.md): Authenticate to the Bonya API with a personal API key or a session JWT
- [Build, run, and preview a web app](https://docs.bonya.ai/tutorials/build-run-preview-a-web-app.md): Get a small web app running inside a sandbox and reachable at a public preview URL, entirely from the CLI
- [Run a one-off script and collect its output](https://docs.bonya.ai/tutorials/run-a-one-off-script.md): Push a script into a disposable sandbox, run it, and see its full result — the CLI's built-in way to do a one-off batch run
- [A persistent session you can walk away from and come back to](https://docs.bonya.ai/tutorials/persistent-dev-session.md): Start a long-running process in a managed session, disconnect on purpose, and reattach later — even after the sandbox has suspended and resumed
- [Sandboxes](https://docs.bonya.ai/concepts/sandboxes.md): The compute resource at the center of the Bonya API
- [Templates](https://docs.bonya.ai/concepts/templates.md): The image a sandbox is created from
- [Exec](https://docs.bonya.ai/concepts/exec.md): Three ways to run a command in a sandbox
- [Sessions](https://docs.bonya.ai/concepts/sessions.md): Long-lived, named command sessions inside a sandbox
- [Files](https://docs.bonya.ai/concepts/files.md): Read, write, and manage files on a sandbox's filesystem
- [Previews](https://docs.bonya.ai/concepts/previews.md): Expose a port running inside a sandbox as an HTTPS URL
- [Snapshots](https://docs.bonya.ai/concepts/snapshots.md): Capture a sandbox's disk state and restore or fork it
- [Jobs](https://docs.bonya.ai/concepts/jobs.md): Managed, tracked runs of a command or script
- [Organizations](https://docs.bonya.ai/concepts/organizations.md): Multi-tenant context and administration
- [API keys](https://docs.bonya.ai/concepts/api-keys.md): Issue and revoke personal API keys
- [Errors](https://docs.bonya.ai/concepts/errors.md): How the Bonya API reports failures
- [Idempotency](https://docs.bonya.ai/concepts/idempotency.md): Safely retry create requests with the Idempotency-Key header
- [WebSockets](https://docs.bonya.ai/concepts/websockets.md): How streaming exec and session attach work over WebSocket
- [Run a command](https://docs.bonya.ai/guides/run-a-command.md): Choose between buffered exec, TTY exec, and managed sessions
- [Transfer files](https://docs.bonya.ai/guides/transfer-files.md): Upload, download, list, and inspect files on a sandbox
- [Expose a preview](https://docs.bonya.ai/guides/expose-a-preview.md): Publish a port running inside a sandbox as an HTTPS URL
- [Snapshot a sandbox](https://docs.bonya.ai/guides/snapshot-a-sandbox.md): Capture a running sandbox's disk state
- [Manage your team](https://docs.bonya.ai/guides/manage-your-team.md): Use a shared organization from the CLI, SDKs, and raw REST calls
- [Examples](https://docs.bonya.ai/guides/examples.md): Every core operation, side by side across cURL, the CLI, and every SDK
- [Overview](https://docs.bonya.ai/cli-reference/overview.md): What the bonya CLI is, how to install it, and how it resolves sandboxes and config
- [Configuration](https://docs.bonya.ai/cli-reference/configuration.md): Flag, environment variable, and saved-login precedence, the config file, and non-interactive behavior
- [login](https://docs.bonya.ai/cli-reference/login.md): Authenticate the CLI, either via your browser or with an existing API key
- [console](https://docs.bonya.ai/cli-reference/console.md): Open an interactive shell in a sandbox
- [create](https://docs.bonya.ai/cli-reference/create.md): Create a new sandbox from a template
- [Sandboxes](https://docs.bonya.ai/cli-reference/sandboxes.md): list, get, delete, and exec — inspecting and managing sandboxes you already have
- [fs](https://docs.bonya.ai/cli-reference/fs.md): Remote filesystem operations on a sandbox — read, write, upload, download, list, stat, mkdir, rm, mv
- [session](https://docs.bonya.ai/cli-reference/session.md): Managed session operations on a sandbox — create, list, attach, kill
- [preview](https://docs.bonya.ai/cli-reference/preview.md): Publish, list, and delete preview URLs for a port running inside a sandbox
- [snapshot](https://docs.bonya.ai/cli-reference/snapshot.md): Create and delete snapshots of a sandbox's state
- [org](https://docs.bonya.ai/cli-reference/org.md): Choose which organization your commands act in by default
- [Account](https://docs.bonya.ai/cli-reference/account.md): whoami, logout, and version
- [Installation](https://docs.bonya.ai/sdks/typescript/installation.md): Install and configure the TypeScript SDK
- [Usage](https://docs.bonya.ai/sdks/typescript/usage.md): Sandboxes, exec, sessions, files, previews, snapshots, jobs, templates, and secrets from TypeScript
- [Installation](https://docs.bonya.ai/sdks/python/installation.md): Install and configure the Python SDK
- [Usage](https://docs.bonya.ai/sdks/python/usage.md): Sandboxes, exec, sessions, files, previews, snapshots, jobs, templates, and secrets from Python
- [Installation](https://docs.bonya.ai/sdks/go/installation.md): Install and configure the Go SDK
- [Usage](https://docs.bonya.ai/sdks/go/usage.md): Sandboxes, exec, sessions, files, previews, snapshots, jobs, and templates from Go
- [Overview](https://docs.bonya.ai/mcp/overview.md): Manage Bonya sandboxes from any MCP client
- [Setup](https://docs.bonya.ai/mcp/setup.md): Install and connect the Bonya MCP server
- [Tools](https://docs.bonya.ai/mcp/tools.md): Tools exposed by the Bonya MCP server
- [List templates](https://docs.bonya.ai/api-reference/templates/list-templates.md): The organization's templates, each at its latest revision.
- [Create a template](https://docs.bonya.ai/api-reference/templates/create-a-template.md): Validates the configuration, resolves the image to a digest, and publishes revision 1.
- [Get a template](https://docs.bonya.ai/api-reference/templates/get-a-template.md)
- [Delete a template](https://docs.bonya.ai/api-reference/templates/delete-a-template.md)
- [Update a template](https://docs.bonya.ai/api-reference/templates/update-a-template.md): Omitted fields keep their current value. Changing the configuration publishes a new immutable revision.
- [List registry connections](https://docs.bonya.ai/api-reference/registry-connections/list-registry-connections.md): Stored credentials for pulling private container images. Passwords are never returned.
- [Create a registry connection](https://docs.bonya.ai/api-reference/registry-connections/create-a-registry-connection.md)
- [Delete a registry connection](https://docs.bonya.ai/api-reference/registry-connections/delete-a-registry-connection.md)
- [Update a registry connection](https://docs.bonya.ai/api-reference/registry-connections/update-a-registry-connection.md)
- [Validate a registry connection](https://docs.bonya.ai/api-reference/registry-connections/validate-a-registry-connection.md): Resolves an image through the connection and returns its digest.
- [List secrets](https://docs.bonya.ai/api-reference/secrets/list-secrets.md): Write-only secrets. Names and timestamps are returned, never values.
- [Create a secret](https://docs.bonya.ai/api-reference/secrets/create-a-secret.md)
- [Delete a secret](https://docs.bonya.ai/api-reference/secrets/delete-a-secret.md)
- [Update a secret](https://docs.bonya.ai/api-reference/secrets/update-a-secret.md)
- [List secret sets](https://docs.bonya.ai/api-reference/secrets/list-secret-sets.md): Named groups of environment variables injected into sandboxes and jobs via secret_sets. Key names are returned, never values.
- [Create a secret set](https://docs.bonya.ai/api-reference/secrets/create-a-secret-set.md)
- [Get a secret set](https://docs.bonya.ai/api-reference/secrets/get-a-secret-set.md)
- [Delete a secret set](https://docs.bonya.ai/api-reference/secrets/delete-a-secret-set.md)
- [Update a secret set](https://docs.bonya.ai/api-reference/secrets/update-a-secret-set.md): Publishes a new revision. Pass the current revision to guard against concurrent edits.
- [List sandboxes](https://docs.bonya.ai/api-reference/sandboxes/list-sandboxes.md): Paginated with page_size/page_token, optionally filtered by states. Deleted sandboxes are not listed.
- [Create a sandbox](https://docs.bonya.ai/api-reference/sandboxes/create-a-sandbox.md): Returns 202 Accepted immediately by default; pass ?wait=ready to block until the sandbox is ready, which returns 201 Created instead.
- [List GPU options](https://docs.bonya.ai/api-reference/sandboxes/list-gpu-options.md): The GPU type and count combinations a sandbox can be created with.
- [Get a sandbox](https://docs.bonya.ai/api-reference/sandboxes/get-a-sandbox.md)
- [Delete a sandbox](https://docs.bonya.ai/api-reference/sandboxes/delete-a-sandbox.md): Synchronous teardown. Returns the sandbox in its final state. An unknown or cross-org sandbox_id returns 404; a sandbox in a state that cannot be deleted right now (for example waking) returns 409.
- [Pause a sandbox](https://docs.bonya.ai/api-reference/sandboxes/pause-a-sandbox.md): Forces a pause and answers when the requested stage is reached. warm resumes fastest; cold frees more resources. A paused sandbox wakes on keepalive, on exec or file access, or on incoming traffic.
- [Hold a sandbox awake](https://docs.bonya.ai/api-reference/sandboxes/hold-a-sandbox-awake.md): Places an expiring keep-awake hold. A paused sandbox is woken. Returns 503 with Retry-After while the wake is in progress.
- [Mint an exec capability](https://docs.bonya.ai/api-reference/sandboxes/mint-an-exec-capability.md): Issues a fresh exec capability token for a sandbox whose earlier token has expired. Existing unexpired tokens stay valid.
- [Replace the network policy](https://docs.bonya.ai/api-reference/sandboxes/replace-the-network-policy.md)
- [Fork a sandbox](https://docs.bonya.ai/api-reference/sandboxes/fork-a-sandbox.md): Creates count new sandboxes with the source's memory and disk, on the source's node. 201 when every child is running, 200 when some failed (see each child's state), 202 on a repeat whose first fork is still running.
- [List a sandbox's snapshots](https://docs.bonya.ai/api-reference/snapshots/list-a-sandboxs-snapshots.md)
- [Create a named snapshot](https://docs.bonya.ai/api-reference/snapshots/create-a-named-snapshot.md): 201 once published; 202 on a repeat whose first write is still running.
- [Get a snapshot](https://docs.bonya.ai/api-reference/snapshots/get-a-snapshot.md)
- [Delete a snapshot](https://docs.bonya.ai/api-reference/snapshots/delete-a-snapshot.md)
- [List preview URLs](https://docs.bonya.ai/api-reference/previews/list-preview-urls.md): List preview URLs for a sandbox. Never returns capabilities.
- [Create a preview URL](https://docs.bonya.ai/api-reference/previews/create-a-preview-url.md): Returns the preview. A private preview also returns a grant whose token is shown only on this response; 201 for a new preview, 200 when the Idempotency-Key repeats an earlier create.
- [Get a preview URL](https://docs.bonya.ai/api-reference/previews/get-a-preview-url.md)
- [Delete a preview URL](https://docs.bonya.ai/api-reference/previews/delete-a-preview-url.md): Returns the deleted preview.
- [List access grants](https://docs.bonya.ai/api-reference/previews/list-access-grants.md)
- [Create an access grant](https://docs.bonya.ai/api-reference/previews/create-an-access-grant.md): The token and exchange_url are shown only on this response.
- [Revoke an access grant](https://docs.bonya.ai/api-reference/previews/revoke-an-access-grant.md)
- [Renew an access grant](https://docs.bonya.ai/api-reference/previews/renew-an-access-grant.md)
- [Run a command (TTY)](https://docs.bonya.ai/api-reference/exec/run-a-command-tty.md): A transient, interactive TTY session over a WebSocket upgrade. The START frame carries a TTYStartRequest.
- [Run a command (buffered)](https://docs.bonya.ai/api-reference/exec/run-a-command-buffered.md): Synchronous, non-TTY exec — JSON body in, JSON body out.
- [List sessions](https://docs.bonya.ai/api-reference/sessions/list-sessions.md): Never wakes a suspended sandbox — it answers from the suspend-time snapshot instead.
- [Create a session](https://docs.bonya.ai/api-reference/sessions/create-a-session.md): Keyed by name. Creating over a live session returns 409 session_exists; replace only applies to a terminal (already-exited) session, never a running or attached one.
- [Attach to a session](https://docs.bonya.ai/api-reference/sessions/attach-to-a-session.md): A WebSocket upgrade. The START frame carries an AttachStartRequest.
- [Kill a session](https://docs.bonya.ai/api-reference/sessions/kill-a-session.md)
- [Read a file](https://docs.bonya.ai/api-reference/filesystem/read-a-file.md): Returns the raw file contents as application/octet-stream.
- [Write a file](https://docs.bonya.ai/api-reference/filesystem/write-a-file.md): The request body is the raw file contents as application/octet-stream.
- [List a directory](https://docs.bonya.ai/api-reference/filesystem/list-a-directory.md)
- [Get file metadata](https://docs.bonya.ai/api-reference/filesystem/get-file-metadata.md)
- [Create a directory](https://docs.bonya.ai/api-reference/filesystem/create-a-directory.md)
- [Rename or move a file](https://docs.bonya.ai/api-reference/filesystem/rename-or-move-a-file.md)
- [Delete a file or directory](https://docs.bonya.ai/api-reference/filesystem/delete-a-file-or-directory.md)
- [List job runs](https://docs.bonya.ai/api-reference/jobs/list-job-runs.md): A tenant's runs, newest first, optionally filtered to sandbox_id or schedule_id.
- [Create a job](https://docs.bonya.ai/api-reference/jobs/create-a-job.md): Run or start a job on a new or existing sandbox. wait=false (default) starts durably and returns run_id immediately; wait=true blocks for the result, bounded by the caller's own request timeout.
- [Get a job run](https://docs.bonya.ai/api-reference/jobs/get-a-job-run.md): Full run detail, including the stored spec that started it and an activity timeline.
- [Cancel a job run](https://docs.bonya.ai/api-reference/jobs/cancel-a-job-run.md): Requests cancellation rather than forcibly terminating, so the run's own cleanup (e.g. deleting a sandbox it created) still executes.
- [List job schedules](https://docs.bonya.ai/api-reference/job-schedules/list-job-schedules.md)
- [Create a job schedule](https://docs.bonya.ai/api-reference/job-schedules/create-a-job-schedule.md)
- [Get a job schedule](https://docs.bonya.ai/api-reference/job-schedules/get-a-job-schedule.md)
- [Delete a job schedule](https://docs.bonya.ai/api-reference/job-schedules/delete-a-job-schedule.md)
- [Update a job schedule](https://docs.bonya.ai/api-reference/job-schedules/update-a-job-schedule.md)
- [Pause or resume a job schedule](https://docs.bonya.ai/api-reference/job-schedules/pause-or-resume-a-job-schedule.md)
- [Trigger a job schedule](https://docs.bonya.ai/api-reference/job-schedules/trigger-a-job-schedule.md): Fires one run immediately, overriding the schedule's own timing.
- [List organizations](https://docs.bonya.ai/api-reference/organizations/list-organizations.md): Organizations the caller belongs to, with their role in each. JWT provisioning operation; API keys are refused.
- [Create an organization](https://docs.bonya.ai/api-reference/organizations/create-an-organization.md): Creates an organization owned by the caller. JWT provisioning operation; API keys are refused.
- [Get an organization](https://docs.bonya.ai/api-reference/organizations/get-an-organization.md): Any member may read; a non-member gets 404, never 403.
- [Rename an organization](https://docs.bonya.ai/api-reference/organizations/rename-an-organization.md): Owner only. Organization deletion is out of scope.
- [List members](https://docs.bonya.ai/api-reference/organizations/list-members.md): Any member of the organization may list.
- [Remove a member](https://docs.bonya.ai/api-reference/organizations/remove-a-member.md): Administrative removal (owner only) and member self-leave share this verb. Removing the final owner is 409 final_owner, which is also why the sole owner of a personal organization cannot leave it.
- [Update a member's role](https://docs.bonya.ai/api-reference/organizations/update-a-members-role.md): Owner only. Demoting the final owner returns 409 final_owner.
- [Get usage and credit balance](https://docs.bonya.ai/api-reference/organizations/get-usage-and-credit-balance.md): Owner or billing role. Reports total recorded usage and its current settled credit balance; both are unbounded (all usage recorded so far), not scoped to a billing period.
- [Get a usage breakdown](https://docs.bonya.ai/api-reference/organizations/get-a-usage-breakdown.md): Owner or billing role. from and to are both required RFC 3339 timestamps, unlike GET .../usage's all-time default; from must precede to. Reports the two supported billable metrics with their share of priced usage and each one's heaviest consumer.
- [Get a usage time series](https://docs.bonya.ai/api-reference/organizations/get-a-usage-time-series.md): Owner or billing role. from and to are both required; bucket is hour or day and defaults to day. Only non-empty buckets are returned. estimated_cents is either present on every point or absent from every point: one price read prices the whole series.
- [List invitations](https://docs.bonya.ai/api-reference/invitations/list-invitations.md): Dashboard-facing; Supabase JWT required, API keys rejected. Owner only.
- [Create an invitation](https://docs.bonya.ai/api-reference/invitations/create-an-invitation.md): Dashboard-facing; owner only. The response carries the raw token exactly once and no acceptance URL: the dashboard builds .../invitations/accept#token=... itself, because TApi does not know the dashboard's origin. A live invitation already addressed to the same address is 409 lifecycle_conflict; a p…
- [Revoke an invitation](https://docs.bonya.ai/api-reference/invitations/revoke-an-invitation.md)
- [Accept an invitation](https://docs.bonya.ai/api-reference/invitations/accept-an-invitation.md): Dashboard-facing; the dashboard reads the token from the URL fragment and posts it in the body. The invitation must have been issued to the authenticated caller's own address, compared case-insensitively; a token alone is not enough. A valid acceptance provisions and consumes the invite in one trans…
- [List API keys](https://docs.bonya.ai/api-reference/api-keys/list-api-keys.md): JWT-only; keys can never manage keys. JWT provisioning operation.
- [Create an API key](https://docs.bonya.ai/api-reference/api-keys/create-an-api-key.md): JWT-only; the secret is shown exactly once. JWT provisioning operation.
- [Revoke an API key](https://docs.bonya.ai/api-reference/api-keys/revoke-an-api-key.md): JWT-only.
- [Start a device login](https://docs.bonya.ai/api-reference/device-login/start-a-device-login.md): Unauthenticated; mints a single-use device-login token and the dashboard URL the CLI opens a browser to. No request body.
- [Approve a device login](https://docs.bonya.ai/api-reference/device-login/approve-a-device-login.md): JWT-only; approves a CLI device-login token. JWT provisioning operation.
- [Poll a device login](https://docs.bonya.ai/api-reference/device-login/poll-a-device-login.md): Unauthenticated; the token in the body is the credential. Always 200: pending, approved (carries the api_key exactly once), or expired. An unknown token is 404.

## OpenAPI Specs

- [openapi](/api-reference/openapi.yaml)


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