> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dataerai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Tools sandbox

> A ready-to-run container with the dataerai CLI and Python SDK installed — authenticate and move data against any DataErai instance, isolated from the rest of your machine.

The **tools sandbox** is the fastest way to start using DataErai from the command
line without installing anything on your host. It's a small container with the
[`dataerai` CLI](/cli/overview) and the [Python SDK](/sdks/python) already
installed and on `PATH`, ready to [authenticate](/cli/authenticate) and move
data. Point it at whichever instance you use — your login and files persist
between runs.

<Note>
  This is the **client** side of DataErai — the same tools a user installs. It
  needs nothing from the server or a local dev stack; it just talks to an
  instance over HTTPS.
</Note>

## Quick start

<Steps>
  <Step title="Get the repository">
    The sandbox lives under `sandbox/` in the repository.

    ```bash theme={null}
    cd sandbox
    ```
  </Step>

  <Step title="Build and open a shell">
    `run.sh` builds the image the first time and drops you into a shell pointed
    at the chosen instance:

    ```bash theme={null}
    ./run.sh prod         # against https://api.dataerai.com
    ```
  </Step>

  <Step title="Sign in">
    Inside the shell, use the browserless device flow (it prints a URL and a code
    to approve in your browser):

    ```bash theme={null}
    dataerai auth login --device
    ```
  </Step>

  <Step title="Move data">
    Describe the asset in a small JSON metadata file, then upload a file into a
    collection and download an asset back:

    ```bash theme={null}
    cat > meta.json <<'JSON'
    { "title": "My dataset", "owner_type": "project", "owner_id": "<project-uuid>" }
    JSON
    dataerai upload --collection <collection-uuid> --metadata meta.json --file data.csv
    dataerai download --asset <asset-uuid> --output .
    ```

    The shell starts in `~/workspace`, which is the `sandbox/workspace/` folder
    on your host — so files you drop there are right here (`data.csv`), and
    downloads (`--output .`) come back out the same way. See
    [CLI commands](/cli/commands) for the full flag reference.
  </Step>
</Steps>

## Choose an instance

`./run.sh <profile>` selects the target instance from `sandbox/env/<profile>.env`:

| Profile  | Instance                                                               |
| -------- | ---------------------------------------------------------------------- |
| `prod`   | `https://api.dataerai.com` — production (the default)                  |
| `local`  | `http://host.docker.internal:8003` — a console dev stack on your host  |
| `custom` | copy `env/custom.env.example` → `env/custom.env` for your organization |

```bash theme={null}
./run.sh prod                       # interactive shell against production
./run.sh local dataerai auth status # one-off command against a local stack
```

<Tip>
  Each profile just sets `DATAERAI_SERVER` (and `DATAERAI_CLIENT_ID`). To use
  your institution's instance, copy the example profile and set its URL.
</Tip>

## Install pathways

The sandbox mirrors the documented install pathways so you can use the one that
matches how you'd install DataErai for real:

<CardGroup cols={2}>
  <Card title="CLI" icon="terminal">
    The `dataerai` binary is built from `cli/` (the [CLI install](/cli/overview))
    and placed on `PATH`.
  </Card>

  <Card title="Python SDK" icon="python">
    Installed with `pip`. Choose the source:

    ```bash theme={null}
    SDK_INSTALL=local ./run.sh prod   # the bundled SDK source (default)
    SDK_INSTALL=pypi  ./run.sh prod   # pip install dataerai-sdk (the published SDK)
    ```

    <Note>
      `local` (the default) installs the in-repo source — handy for testing local
      changes. `pypi` installs the published **`dataerai-sdk`** (the bare name
      `dataerai` on PyPI is an unrelated package).
    </Note>
  </Card>
</CardGroup>

## Notebooks

For interactive work, run the same client as a **JupyterLab** server:

```bash theme={null}
./run.sh prod notebooks     # → http://127.0.0.1:8888
```

It shares your login with the shell (sign in once, in either) and ships an
example `01_getting_started.ipynb`. The SDK's blocking methods read naturally in
a notebook. Same instance profiles apply.

## Use the Python SDK

The SDK is blocking and drives the same CLI binary, so it works the same in the
sandbox as in a script:

```python theme={null}
from dataerai import DataeraiClient

with DataeraiClient(binary_path="/usr/local/bin/dataerai") as client:
    print(client.auth_status())
    result = client.upload(
        "/home/dataerai/workspace/data.csv",
        title="My dataset", owner_type="project", owner_id="<project-id>",
    )
    print("uploaded", result.asset_id)
```

See the [Python SDK reference](/sdks/python) for the full API.

## What's inside

* the `dataerai` CLI (built from `cli/`) on `PATH`
* the `dataerai` Python SDK (`pip`-installed, zero runtime dependencies)
* a `bash` shell with `curl` and `jq`
* a non-root user; credentials in `~/.config/dataerai` (a named volume that
  survives restarts) and your files in `~/workspace`

Everything is defined in `sandbox/` (`Dockerfile`, `compose.yaml`, `env/`,
`run.sh`) — see `sandbox/README.md`.

## Without the helper script

```bash theme={null}
cd sandbox
docker compose --env-file env/prod.env run --rm --build sandbox
```