Tools sandbox

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 and the Python SDK already installed and on PATH, ready to authenticate and move data. Point it at whichever instance you use — your login and files persist between runs.

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.

Quick start

Get the repository

The sandbox lives under sandbox/ in the repository.

cd sandbox

Build and open a shell

run.sh builds the image the first time and drops you into a shell pointed at the chosen instance:

./run.sh prod         # against https://api.dataerai.com

Inside the shell, use the browserless device flow (it prints a URL and a code to approve in your browser):

dataerai auth login --device

Move data

Describe the asset in a small JSON metadata file, then upload a file into a collection and download an asset back:

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 for the full flag reference.

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

./run.sh prod                       # interactive shell against production
./run.sh local dataerai auth status # one-off command against a local stack

Each profile just sets DATAERAI_SERVER (and DATAERAI_CLIENT_ID). To use your institution’s instance, copy the example profile and set its URL.

Install pathways

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

CLI

The dataerai binary is built from cli/ (the CLI install) and placed on PATH.

Python SDK

Installed with pip. Choose the source:

SDK_INSTALL=local ./run.sh prod   # the bundled SDK source (default)
SDK_INSTALL=pypi  ./run.sh prod   # pip install dataerai-sdk (the published SDK)

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

Notebooks

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

./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:

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

cd sandbox
docker compose --env-file env/prod.env run --rm --build sandbox

Command-line

SDKs

Integrations

Metadata extraction

Quick start

Choose an instance

Install pathways

CLI

Python SDK

Notebooks

Use the Python SDK

What’s inside

Without the helper script

​Quick start

​Choose an instance

​Install pathways

CLI

Python SDK

​Notebooks

​Use the Python SDK

​What’s inside

​Without the helper script

Quick start

Choose an instance

Install pathways

Notebooks

Use the Python SDK

What’s inside

Without the helper script