The ibby command

The ibby command line tool. One command for each API operation, a --json mode for scripts and agents, and exit codes you can rely on.

npm install --global @ibby-ai/cli

It needs Node 20 or later. ibby --help lists every command with a worked example, and ibby <group> <command> --help shows a command’s options.

Your key

The tool reads your key only from IBBY_API_KEY. It never takes the key as an argument, so the key stays out of shell history and process lists. Paste it without echoing it:

read -rs IBBY_API_KEY && export IBBY_API_KEY

To reach another platform, such as a staging one, set IBBY_BASE_URL or pass --base-url.

Sandboxes

ibby sandboxes create --workdir /work --lifetime-ms 60000 --cpu 0.5 --memory-mib 512
ibby sandboxes get sbx_...
ibby sandboxes make-directories sbx_... /work/in /work/out
echo 'a,b' > data.csv
ibby sandboxes write-files sbx_... --file /work/in/data.csv=./data.csv
ibby sandboxes list-files sbx_... /work/in
ibby sandboxes read-file sbx_... /work/in/data.csv
ibby sandboxes read-file sbx_... /work/in/data.csv --output ./copy.csv
ibby sandboxes remove sbx_...

write-files takes one --file REMOTE=LOCAL per file. Use - as LOCAL to read standard input, byte for byte. read-file prints the file’s bytes as they are, or saves them with --output.

create also takes --image img_... to run on an image you built (see Images), and --store-mount PATH --store-prefix PREFIX, together, to attach part of the lane’s store folder read-only inside the working directory:

ibby sandboxes create --workdir /work --store-mount /work/in --store-prefix runs/1/

To remove a sandbox by the name you gave it, for cleanup after a crash:

ibby sandboxes create --workdir /work --name nightly-report
ibby sandboxes remove-by-name nightly-report

Running commands

Put the command after --. No shell runs unless you run one:

ibby sandboxes create --workdir /work
ibby sandboxes exec sbx_... -- ls -la /work
ibby sandboxes exec sbx_... --timeout-ms 30000 --env GREETING=hello -- sh -c 'echo $GREETING'
ibby sandboxes remove sbx_...

exec prints the command’s standard output and exits with the command’s own exit code, or 124 when it timed out. In this version a command that timed out returns no output. Everything after -- belongs to the command, so -- tool --json passes --json to the tool. A command is never retried on its own.

Images

Write the recipe to a file, then build it. The concepts page explains recipes.

echo '{"base":{"reference":"python:3.13-slim","digest":"sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"},"packages":[]}' > recipe.json
ibby images build ./recipe.json
ibby images get img_...
ibby sandboxes create --workdir /work --image img_...

images get fails with image_not_built when the image has no build on the lane’s current provider, which happens only after a lane changes provider; build the recipe again. images build prints the build job. When it is done, its result names the image. Use - as the file to read the recipe from standard input. A file that is not JSON exits with code 2; a recipe that breaks the rules gets 400 invalid_request from the API.

Jobs

ibby jobs get job_...
ibby jobs cancel job_...

Usage

ibby usage --since 2026-11-01T00:00:00Z

Lists your lane’s runs and their estimated costs as a table with fixed columns, then the totals. Every cost is an estimate. The usage page lists the columns.

Scripts and agents

Add --json to any command to print the API’s own JSON instead of text:

ibby sandboxes create --workdir /work --json

Where the API sends no JSON, the tool prints a fixed shape:

A failed call prints { "error": { "code", "message", "request_id", "status" } } on standard error.

Exit codes: