nf-ai-sandbox-cli

Installs the ai-sandbox command. The distribution is named nf-ai-sandbox-cli because ai-sandbox-cli was already taken on PyPI.

Section 8.2 / Build Order 42.

pip install -e .   # also installs the ai_sandbox SDK as a dependency

ai-sandbox login
ai-sandbox launch --template llama-3-8b
ai-sandbox launch --gpu H100 --provider auto --template llama-3-8b --hours 4
ai-sandbox status <instance-id>
ai-sandbox templates
ai-sandbox whoami
ai-sandbox logout

login uses the same browser-based device-authorization flow described in ai_sandbox's README / Section 8.2 — never a manual API key copy-paste. Credentials (including a refresh token — see Auth refresh below) are stored at ~/.ai-sandbox/credentials.json and are shared with any script using from ai_sandbox import Client.

Commands

Every command accepts --api-url (or AI_SANDBOX_API_URL) to point at a non-default backend; otherwise it resolves the same way the SDK's Client does (stored credentials file, then http://localhost:8000).

Reaching a non-Jupyter service in your sandbox (OI-42)

The platform only ever exposes SSH and Jupyter publicly, by design (Master Spec §21) — a security boundary the project deliberately keeps narrow rather than widening per-template. If you're running TensorBoard, a Gradio demo, or anything else with its own port, tunnel reuses the SSH access you already have instead of opening a new port on the instance:

ai-sandbox tunnel <instance-id> --port 6006   # TensorBoard, say
# now open http://localhost:6006

No provider or platform change, no new attack surface — this is the same ssh -L port-forwarding pattern you'd use manually, just wrapped for convenience.

Auth refresh

You never need to re-run login just because time has passed. Access tokens are short-lived by design; the CLI (via ai_sandbox.Client) transparently exchanges the stored refresh token for a new access token on the first 401 it sees and retries the request once, with no visible interruption. This matters most for launch, which can poll for minutes while a sandbox provisions. Only a second 401 — meaning the refresh token itself is gone, e.g. after logout or on a machine that's been idle long enough for it to expire — surfaces as Not logged in. Run \ai-sandbox login` first.`. See the SDK README's "Token refresh" section for the full mechanism.

Error handling

Every command exits non-zero on failure and prints a one-line message to stderr rather than a raw traceback. The pattern throughout main.py is to catch the specific ai_sandbox exception types that call for different wording (NotAuthenticatedError, DeviceLoginDeniedError, DeviceLoginTimeoutError, FreeTextReviewQueuedError) and fall back to the AiSandboxError base class for everything else. launch additionally treats FreeTextReviewQueuedError as a non-error: no instance was created, but the request was queued for admin review, so it prints the review queue id and exits 0. See ai_sandbox's README for the full exception hierarchy these messages are built from.