Metadata-Version: 2.4
Name: stackbox
Version: 0.5.0
Summary: The stackbox command line: run sandboxes on the hosted stackbox router, and see where they go and what they cost
Keywords: sandbox,opensandbox,e2b,modal,daytona,cloudflare,blaxel,agents,cli
Author: Stacktrace AI, Inc
Author-email: Stacktrace AI, Inc <founders@stacktrace.ai>
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Dist: httpx>=0.27
Requires-Dist: opensandbox>=1.2.0,<2
Requires-Python: >=3.11
Project-URL: Homepage, https://stacktrace.ai
Project-URL: Console, https://app.box.stacktrace.ai
Description-Content-Type: text/markdown

# stackbox

The command line for [stackbox](https://stacktrace.ai), the hosted router for sandbox
providers. stackbox puts E2B, Modal, Daytona, Blaxel and Cloudflare Containers behind one
OpenSandbox-compatible API and one key.

## Quickstart

Get an API key from your org's admin, or create one in the console at
<https://app.box.stacktrace.ai>. Then install the client, log in once, and run a command:

```bash
pip install stackbox
```

```bash
stackbox auth login
```

```bash
stackbox run --name hello ubuntu:24.04 -- echo hello
```

`stackbox run` creates a sandbox, runs the command and streams its output. The first
line on stderr gives the sandbox's name, its id and the provider that got it. While the
sandbox starts, a live line on the terminal shows each provider that stackbox tries. The sandbox stays
running for your next commands:

```bash
stackbox exec hello -- echo again
```

```bash
stackbox delete hello
```

Without `--name`, the sandbox gets a generated name, such as `brave-otter`. Add `--rm` to delete
the sandbox after the command.

## Commands

A bare verb acts on a sandbox, as in Docker: `stackbox run`, `stackbox list`. Anything else has
a noun: `stackbox image list`. Every command takes `--json`.

| Command | What it does |
|---|---|
| `stackbox auth login`, `logout`, `status` | Saves, removes or checks the org API key |
| `stackbox run IMAGE -- CMD…` | Creates a sandbox and runs `CMD` in it. `--rm` deletes the sandbox after `CMD` |
| `stackbox create IMAGE` | Creates a sandbox and waits until it is ready |
| `stackbox create IMAGE --dry-run` | Shows where the sandbox would go, and why, and creates nothing |
| `stackbox exec SANDBOX -- CMD…` | Runs `CMD` in a running sandbox |
| `stackbox list [--all]` | Shows the org's running sandboxes, newest first, with how long each one ran and its estimated cost. `--all` adds ended ones |
| `stackbox show SANDBOX` | Shows where a sandbox went, each attempt, and its estimated cost |
| `stackbox delete SANDBOX…` | Deletes sandboxes |
| `stackbox image list [IMAGE]` | Shows each prepared image, and the providers where it is ready, building or failed |
| `stackbox image show IMAGE` | Shows an image's status on each provider, with the first line of each error. `--json` has the full error |
| `stackbox image prepare IMAGE` | Prepares an image on each provider, so its sandboxes start fast |
| `stackbox provider list` | Shows each connected provider: status, capacity and warm pools |
| `stackbox usage [--since 24h]` | Shows sandbox time and estimated cost for each provider |
| `stackbox doctor` | Checks the API, the key, the providers and all recorded images |

`SANDBOX` is a sandbox's name, its id, or the start of its id when no other sandbox's id starts
the same way.

`run` and `create` take these options before `--`:

| Option | What it does |
|---|---|
| `--name NAME` | Sets the name. The default is a generated one |
| `--cpu CPU` | Sets the vCPUs: `2`, `0.5` or `500m`. The default is the provider's |
| `--memory MEMORY` | Sets the memory: `4Gi`, `512Mi`, or GiB as a number, `4`. The default is the provider's |
| `--timeout DURATION` | Sets the sandbox's lifetime, for example `2h`. The default is `30m`. A provider whose limit is shorter is skipped |
| `-e KEY=VALUE` | Sets an environment variable. It can repeat |
| `--strategy S` | Picks providers by `priority`, `cost`, `latency`, `balanced`, `random` or `round-robin` |
| `--providers A,B` | Limits the providers, in order of preference |
| `--max-price USD` | Limits the price per sandbox-hour |

```bash
stackbox run --rm -e GREETING=hi --timeout 1h python:3.13 -- python3 -c 'import os; print(os.environ["GREETING"])'
```

`run` and `exec` exit with the command's exit code. They exit with 125 when
stackbox cannot start the sandbox or run the command, as `docker run` does. Costs are estimates
from list prices, not invoices.

## Set up an org (admins)

1. Sign in to the console at <https://app.box.stacktrace.ai>.
2. Connect providers on the Providers page.
3. Create API keys for your team on the API keys page.

Then prepare the images your team uses, so their first sandboxes start fast, and check the
setup:

```bash
stackbox image prepare python:3.13
```

```bash
stackbox doctor
```

An image that no provider prepared still runs. Its first start is slower.

### Doctor image checks

`stackbox doctor` shows every recorded image and its preparation status on each connected provider.
Failed, incomplete or missing preparations produce warnings without changing the exit code.
An empty image inventory also produces a warning.
Use `stackbox doctor --image IMAGE` to check one image.
This command fails if no provider has prepared that image.
Use `stackbox image show IMAGE` to inspect preparation errors.
These checks read preparation records. They do not create sandboxes or run commands.

### Cloudflare

Connect Cloudflare in the console with your account ID and API token. Stackbox deploys the bridge on your account.
Setup progress and errors appear on the Providers page. You do not need Docker, Node.js or Wrangler on your machine.

Add an image through the normal preparation command:

```bash
stackbox image prepare python:3.13 -p cloudflare
```

Stackbox builds the image, updates the bridge and checks that a sandbox starts before marking it ready.

## Harbor and the OpenSandbox SDKs

stackbox's API is OpenSandbox's. Harbor's `opensandbox` environment, the OpenSandbox SDKs and
`osb` work unchanged. Point them at `api.box.stacktrace.ai` with your API key.

## Configuration

`stackbox auth login` saves the API key in `~/.config/stackbox/config.toml`, with mode 0600.
`STACKBOX_API_KEY` and `STACKBOX_URL` override the file. The client sends the key only to that
URL. It never holds a provider key.

Exit codes of the other commands: 0 when the command did what it says, 1 when the API refused or
failed, and 2 for bad usage or no API key.

## License

Apache-2.0. The hosted service is a separate, proprietary product.
