Skip to main content
This walks through the smallest possible loop: get a key, create a sandbox, run a command in it, clean up. Every example uses the bonya-dev template — see Templates for what that means.
1

Get an API key

Install the CLI and log in — this opens a browser tab for you to approve, then hands the CLI a byk_-prefixed personal API key.
See Authentication for exactly what bonya login does under the hood, and how to mint a key without it. Once you have a key, export it — the CLI and every SDK read this variable by default:
2

Install an SDK (optional)

Skip this if you’re only using the CLI or raw REST.
3

Create a sandbox

A sandbox can name a template_id, or omit it to use the deployment’s configured default template. POST /v1/sandbox returns 202 immediately by default, with the sandbox still CREATING — pass ?wait=ready to block until it’s up and get 201 back instead.
The response body is { "sandbox": { "sandbox_id": "...", "state": "RUNNING", "template_id": "bonya-dev", ... } }. See Sandboxes for the full lifecycle.
4

Run a command

The simplest way to run something is buffered exec — one JSON request, one JSON response, no WebSocket involved. A non-zero exit code is still a 200; check exit_code in the body.
That’s one of three ways to run a command — see Run a command for the WebSocket TTY and managed-session modes, which are what you want for interactive shells or long-running processes.
5

Clean up

Deletion is a synchronous teardown — the call doesn’t return until the sandbox is gone.

Next steps

CLI Reference

Install the bonya CLI and browse every command.

Core Concepts

Learn the sandbox lifecycle, exec, sessions, files, previews, snapshots, and organizations.

MCP Server

Connect Bonya to Claude Desktop, Claude Code, or Cursor.