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

# Quickstart

> Create a sandbox and run a command in under 5 minutes

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](https://docs.bonya.ai/concepts/templates.md) 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.

```shell Homebrew theme={null}
brew install bonyai/tap/bonya
bonya login
```

```shell Install script theme={null}
curl -fsSL https://get.bonya.ai/install.sh | sh
bonya login
```

See [Authentication](https://docs.bonya.ai/authentication.md) 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:

```bash theme={null}
export BONYA_API_KEY=byk_...
```

**2. Install an SDK (optional)**

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

```bash TypeScript theme={null}
npm install @bonya-ai/bonya
```

```bash Python theme={null}
python -m pip install bonya
```

```bash Go theme={null}
go get github.com/bonyai/bonya-sdk-go
```

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

```shell cURL theme={null}
curl -s -X POST "https://api.bonya.ai/v1/sandbox?wait=ready" \
  -H "Authorization: Bearer $BONYA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"template_id": "bonya-dev"}'
```

```shell CLI theme={null}
bonya create --template bonya-dev
```

```ts TypeScript theme={null}
import { Bonya } from "@bonya-ai/bonya";

const client = new Bonya();
const sandbox = await client.createSandbox({ template: "bonya-dev" });
console.log(sandbox.id);
```

```python Python theme={null}
from bonya import Bonya

with Bonya() as client:
    sandbox = client.create_sandbox(template="bonya-dev")
    print(sandbox.id)
```

```go Go theme={null}
client, err := bonya.NewClient()
if err != nil {
    log.Fatal(err)
}
defer client.Close()

ctx := context.Background()
sandbox, err := client.CreateSandbox(ctx, "bonya-dev")
if err != nil {
    log.Fatal(err)
}
fmt.Println(sandbox.ID)
```

The response body is `{ "sandbox": { "sandbox_id": "...", "state": "RUNNING", "template_id": "bonya-dev", ... } }`. See [Sandboxes](https://docs.bonya.ai/concepts/sandboxes.md) 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.

```shell cURL theme={null}
curl -s -X POST "https://api.bonya.ai/v1/sandbox/$SANDBOX_ID/exec" \
  -H "Authorization: Bearer $BONYA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"cmd": ["echo", "hello from bonya"]}'
```

```shell CLI theme={null}
bonya exec $SANDBOX_ID -- echo "hello from bonya"
```

```ts TypeScript theme={null}
const result = await sandbox.exec(["echo", "hello from bonya"]);
console.log(result.stdout, result.exitCode);
```

```python Python theme={null}
result = sandbox.exec(["echo", "hello from bonya"])
print(result.stdout, result.exit_code)
```

```go Go theme={null}
result, err := sandbox.Exec(ctx, []string{"echo", "hello from bonya"})
if err != nil {
    log.Fatal(err)
}
fmt.Println(result.Stdout(), result.ExitCode)
```

That's one of three ways to run a command — see [Run a command](https://docs.bonya.ai/guides/run-a-command.md) 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.

```shell cURL theme={null}
curl -s -X DELETE "https://api.bonya.ai/v1/sandbox/$SANDBOX_ID" \
  -H "Authorization: Bearer $BONYA_API_KEY"
```

```shell CLI theme={null}
bonya delete $SANDBOX_ID
```

```ts TypeScript theme={null}
await sandbox.delete();
```

```python Python theme={null}
sandbox.delete()
```

```go Go theme={null}
sandbox.Delete(ctx)
```

## Next steps

> [card] [CLI Reference](https://docs.bonya.ai/cli-reference/overview.md)
>
> Install the bonya CLI and browse every command.

> [card] [Core Concepts](https://docs.bonya.ai/concepts/sandboxes.md)
>
> Learn the sandbox lifecycle, exec, sessions, files, previews, snapshots, and organizations.

> [card] [MCP Server](https://docs.bonya.ai/mcp/overview.md)
>
> Connect Bonya to Claude Desktop, Claude Code, or Cursor.


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