Skip to content

namespace-devbox.md

Latest commit

 

History

History
90 lines (68 loc) · 4.48 KB

namespace-devbox.md

File metadata and controls

90 lines (68 loc) · 4.48 KB
Raw

Namespace Devbox

Read this when you are:

  • choosing provider: namespace-devbox;
  • comparing Namespace Devbox with other delegated or SSH-lease providers;
  • debugging the Namespace CLI lifecycle that backs Crabbox sync and run.

provider: namespace-devbox (aliases namespace, namespace-devboxes) creates or reuses Namespace Devboxes and exposes them to Crabbox as Linux SSH leases. Namespace owns the Devbox lifecycle, SSH config, and auth; Crabbox owns the local checkout sync, command execution, Actions hydration, and run timing. The provider is Linux-only and runs direct from the CLI — it is never brokered through the coordinator.

Setup

Install and authenticate the Namespace CLI (devbox):

devbox login

Crabbox shells out to the devbox binary for create, configure-ssh, list, shutdown, and delete. It reads the generated SSH config from ~/.namespace/ssh/, so a working devbox login session is the only credential Crabbox needs.

Select the provider in config:

provider: namespace-devbox
namespace:
  image: builtin:base
  size: M
  workRoot: /workspaces/crabbox

Commands

crabbox warmup --provider namespace-devbox --namespace-image builtin:base
crabbox run --provider namespace-devbox --id <slug> -- pnpm test
crabbox ssh --provider namespace-devbox --id <slug>
crabbox list --provider namespace-devbox
crabbox stop --provider namespace-devbox <slug>

Lease-acting commands accept either the canonical cbx_… lease ID or the friendly slug via --id <devbox-name-or-slug>.

Provider boundary

Namespace Devbox is an SSH-lease provider, not a delegated-run provider. That distinction shapes the integration:

  • A delegated-run provider owns sync and command transport end to end; Crabbox hands it the workspace and a command and gets results back.
  • Namespace Devbox only owns provisioning: create, the generated SSH config, and list. Crabbox then drives rsync, SSH command execution, Actions hydration, and timing directly against the box, exactly as it does for any other SSH lease.

The provider declares the ssh, crabbox-sync, and cleanup features.

Configuration

Set these under the namespace config section, override per invocation with the matching --namespace-* flag, or via the CRABBOX_NAMESPACE_* environment variables. Flag wins over env, which wins over config file, which wins over the built-in default.

Config key Flag Env var Default Notes
image --namespace-image CRABBOX_NAMESPACE_IMAGE builtin:base Devbox image.
size --namespace-size CRABBOX_NAMESPACE_SIZE M One of S, M, L, XL (case-insensitive).
repository --namespace-repository CRABBOX_NAMESPACE_REPOSITORY (none) Optional repo for Namespace to clone into the Devbox.
site --namespace-site CRABBOX_NAMESPACE_SITE (none) Optional Namespace site.
volumeSizeGB --namespace-volume-size-gb CRABBOX_NAMESPACE_VOLUME_SIZE_GB (none) Persistent volume size in GiB; must be non-negative.
autoStopIdleTimeout --namespace-auto-stop-idle-timeout CRABBOX_NAMESPACE_AUTO_STOP_IDLE_TIMEOUT 30m Namespace idle auto-stop; falls back to Crabbox --idle-timeout if unset.
workRoot --namespace-work-root CRABBOX_NAMESPACE_WORK_ROOT /workspaces/crabbox Crabbox sync root; must be a dedicated absolute subdirectory.
deleteOnRelease --namespace-delete-on-release CRABBOX_NAMESPACE_DELETE_ON_RELEASE false Delete the Devbox on release instead of shutting it down.

The workRoot is validated: it must resolve to an absolute path and may not be a broad system directory (e.g. /, /home, /tmp, or /workspaces itself); choose a dedicated subdirectory such as the default /workspaces/crabbox.

Related docs: