NVIDIA Brev Provider

Read when:

• choosing provider: nvidia-brev;
• using Crabbox on NVIDIA Brev GPU workspaces;
• changing internal/providers/nvidiabrev.

NVIDIA Brev is a direct-only Linux SSH-lease provider. Crabbox shells out to the local brev CLI to create, list, refresh, stop, and delete Brev workspaces. After Brev writes its SSH config, Crabbox uses the normal SSH transport for sync, run, ssh, status, list, and stop.

Crabbox does not store Brev credentials or accept them as flags. Authentication stays with the Brev CLI.

For headless use, Brev also accepts BREV_API_KEY in the environment. This overrides saved Brev credentials. Crabbox asks brev org ls for that key's effective organization before lifecycle operations; the key never becomes a Crabbox flag or config value. Verify the account with brev org ls before creating a workspace.

#Existing claims after an authentication upgrade

Older Crabbox versions could record the saved credentials' organization while Brev used BREV_API_KEY for a different organization. These mismatched claims remain blocked and unchanged after upgrade. Crabbox does not automatically rewrite their ownership.

Run brev org ls and brev ls --json --all with the credentials you used to create the workspace. Verify the workspace ID and organization in the Brev console against the retained claim before taking action. Manage that exact workspace directly through Brev until the claim has been reconciled; use Brev's stop or delete operation when you intend to stop or remove it. Preserve the local claim for diagnosis rather than changing its organization to bypass the check. New Crabbox leases record the effective key's organization correctly.

If the claim belongs to another valid account, use that account's credentials. brev set cannot override BREV_API_KEY; unset or replace the environment key first. Automatic repair of misbound claims is outside this fix.

#Prerequisites

• Install the Brev CLI and authenticate it:

``sh brev login ``

• Confirm Brev can list workspaces:

``sh brev ls --json ``

• For OAuth login, select the organization used for lifecycle operations:

``sh brev set ``

API-key and workspace contexts may provide an explicit organization scope without an active OAuth organization.

• Keep OpenSSH and rsync available locally for Crabbox's SSH workflow.
• Use an account with enough Brev quota and a GPU type that is available in the selected Brev cloud.

#Capabilities

Aliases: brev, nvidia.

#Configuration

provider: nvidia-brev
target: linux
nvidiaBrev:
  cli: brev
  type: ""
  gpuName: A100
  provider: ""
  mode: vm
  launchable: ""
  startupScript: ""
  releaseAction: delete
  target: container
  user: ""
  workRoot: /tmp/crabbox

Defaults:

• cli: brev
• gpuName: A100
• mode: vm
• releaseAction: delete
• target: container
• workRoot: /tmp/crabbox

startupScript follows Brev's native syntax: use an inline command such as pip install torch, or prefix a local file path with @, for example @setup.sh or @/opt/setup.sh. Local @file startup scripts are accepted only from trusted user config, environment overrides, or command-line flags; project config cannot select local files.

Provider flags:

--nvidia-brev-cli
--nvidia-brev-org
--nvidia-brev-type
--nvidia-brev-gpu-name
--nvidia-brev-provider
--nvidia-brev-mode
--nvidia-brev-launchable
--nvidia-brev-startup-script
--nvidia-brev-release-action
--nvidia-brev-target
--nvidia-brev-user
--nvidia-brev-work-root

Environment overrides:

CRABBOX_NVIDIA_BREV_CLI
CRABBOX_NVIDIA_BREV_ORG
CRABBOX_NVIDIA_BREV_TYPE
CRABBOX_NVIDIA_BREV_GPU_NAME
CRABBOX_NVIDIA_BREV_PROVIDER
CRABBOX_NVIDIA_BREV_MODE
CRABBOX_NVIDIA_BREV_LAUNCHABLE
CRABBOX_NVIDIA_BREV_STARTUP_SCRIPT
CRABBOX_NVIDIA_BREV_RELEASE_ACTION
CRABBOX_NVIDIA_BREV_TARGET
CRABBOX_NVIDIA_BREV_USER
CRABBOX_NVIDIA_BREV_WORK_ROOT

nvidiaBrev.org scopes read-only inventory through brev ls --org. Brev's mutating commands and brev refresh do not accept that selector, so Crabbox rejects lifecycle and SSH resolution when org is configured. Use credentials for the desired organization before running mutating Crabbox commands. OAuth users select it with brev set; an environment BREV_API_KEY takes precedence.

#Lifecycle

#Doctor

doctor is read-only. It checks the Brev CLI version and lists the current Brev inventory:

crabbox doctor --provider nvidia-brev
crabbox doctor --provider nvidia-brev --json

It does not create, stop, or delete a workspace.

#Acquire

warmup and run create cost-bearing Brev workspaces:

crabbox warmup --provider nvidia-brev --slug gpu-smoke --keep
crabbox run --provider nvidia-brev -- nvidia-smi

Acquire flow:

1. list existing workspaces to allocate a Crabbox slug;
2. run brev create <name> --detached with the configured Brev selectors;
3. wait for the workspace to report ready;
4. run brev refresh;
5. read the Brev SSH config from ~/.brev/ssh_config;
6. resolve the configured target alias;
7. wait for SSH readiness;
8. write a local Crabbox lease claim and run the normal SSH workflow.

Crabbox names workspaces as crabbox-<slug>-<lease-suffix> so list and cleanup can distinguish Crabbox-owned Brev workspaces from manual ones.

If brev create returns an ambiguous transport error, Crabbox checks inventory for the deterministic workspace name and stores a recovery claim. Non-kept workspaces are deleted when ownership is confirmed; kept workspaces remain manageable by lease ID or slug. Name-only recovery claims report failed until the workspace appears and can be cleared by explicit release after the recovery grace period.

Ordinary status reads inventory and probes an existing generated SSH route without refreshing Brev configuration, starting the workspace, or changing the lease claim. The config bytes must match the digest recorded when Crabbox prepared this workspace in its organization. Missing provenance, a changed config, a missing alias, or failed required certificate renewal reports no endpoint and remains unready. Use status --wait --id <lease> to refresh the route and record its preparation. Older claims need this preparation too. Any Brev rewrite, even an unrelated workspace refresh, can conservatively make an otherwise healthy route unready until it is prepared again. An explicitly selected read-only organization remains inventory-only.

#SSH target selection

nvidiaBrev.target controls which Brev SSH config host Crabbox selects:

• container (default) selects the workspace host alias.
• host selects the <workspace-name>-host alias.

A retained lease remembers this choice across new Crabbox processes and stop/start. An explicit nvidiaBrev.target setting, environment override, or flag changes it; omitting the setting preserves the stored target.

Brev may emit either a direct HostName/Port target or a ProxyCommand. Crabbox uses native OpenSSH to interpret the generated config, including certificate-only Match exec entries and optional certificate/static-key fallback. Crabbox captures the config when it validates the workspace. Run, sync, forwarding, and interactive connections reuse those bytes, so a later Brev refresh cannot redirect an already resolved operation. Each new transport still reevaluates the captured certificate hook. These transports retain Crabbox's session policy instead of inheriting remote commands or forwards.

Printed native SSH commands use Brev's current config file. Regenerate them after changing organizations.

#Release and cleanup

The default release action is delete:

crabbox stop --provider nvidia-brev gpu-smoke

delete records the claim as deleting, clears its SSH endpoint, runs brev delete, and keeps polling until Brev inventory confirms that the workspace is absent. The local claim remains available for a later stop or cleanup retry if polling is interrupted.

Blank, whitespace-only, or malformed inventory output is an error, even when the Brev process exits successfully. Crabbox retains the deleting claim until a retry receives valid inventory confirming absence; that reconciliation does not repeat the delete request.

Crabbox stores the active Brev organization ID in each claim. Because Brev mutations do not accept an organization selector, lifecycle commands reject an active-org mismatch and retain the claim. Run brev set for the lease's original organization, then retry the command.

If the active organization changes while a workspace is being created, Crabbox does not delete from either organization automatically. It retains a recovery claim with both observed organization IDs for manual reconciliation, avoiding deletion of an unrelated same-named workspace.

If nvidiaBrev.releaseAction is stop, Crabbox runs brev stop, keeps the local claim, and records the lease as stopped for later reuse or cleanup.

cleanup only mutates Brev workspaces that have matching local Crabbox claims:

crabbox cleanup --provider nvidia-brev --dry-run
crabbox cleanup --provider nvidia-brev

Manual Brev workspaces and unclaimed Crabbox-looking workspaces are skipped rather than deleted blindly.

#Examples

Run a GPU smoke and delete the workspace after the command:

crabbox run --provider nvidia-brev -- nvidia-smi

Warm a reusable GPU workspace, run a CUDA check, then release it:

crabbox warmup --provider nvidia-brev --slug cuda-box --keep
crabbox run --provider nvidia-brev --id cuda-box --no-sync -- python3 - <<'PY'
print("cuda-ready")
PY
crabbox ssh --provider nvidia-brev --id cuda-box
crabbox status --provider nvidia-brev --id cuda-box --wait
crabbox stop --provider nvidia-brev cuda-box

Choose a different Brev GPU selector:

crabbox run \
  --provider nvidia-brev \
  --nvidia-brev-gpu-name L40S \
  -- nvidia-smi

#Live smoke

The repository live smoke is intentionally separate from default CI because it can create a billable GPU workspace:

CRABBOX_LIVE=1 CRABBOX_LIVE_PROVIDERS=nvidia-brev scripts/live-smoke.sh
CRABBOX_NVIDIA_BREV_LIVE=1 scripts/live-nvidia-brev-smoke.sh

The top-level script dispatches to the provider-specific script with CRABBOX_NVIDIA_BREV_LIVE=1. The provider-specific script builds or reuses bin/crabbox, runs doctor, creates one workspace with --keep=false so partial acquisition failures roll back, proves nvidia-smi through crabbox run, lists the lease, and then deletes the lease with crabbox stop. It prints a stable classification:

• live_nvidia_brev_smoke_passed when the full GPU path passes;
• environment_blocked for missing CLI/auth/configuration;
• provider_quota_blocked for quota or rate-limit failures;
• capacity_blocked when Brev cannot allocate the requested GPU;
• validation_failed when Crabbox output is malformed or missing the smoke lease.

Without CRABBOX_NVIDIA_BREV_LIVE=1, the script exits successfully with classification=environment_blocked reason=CRABBOX_NVIDIA_BREV_LIVE_not_enabled and creates no workspace.

#Cost and privacy discipline

• Treat every warmup or run without an existing --id as cost-bearing.
• Prefer releaseAction: delete for disposable test runs.
• Run crabbox list --provider nvidia-brev --all before and after live tests when auditing inventory.
• Do not put Brev secrets, organization identifiers, private SSH material, or local credential files in repository config, docs, scripts, logs, or command arguments.
• Use neutral slugs and examples in shared repos.

Related docs:

• Provider reference
• Provider backends