Skip to content

feat(cli): add --from flag to sandbox create for unified image sources #88

Description

@drew

Summary

Add a --from flag to nemoclaw sandbox create that provides a unified interface for specifying sandbox image sources. This replaces the current --image flag with a smarter option that accepts multiple input types and resolves them automatically.

Motivation

The nemoclaw-community repo hosts pre-built sandbox images (e.g., openclaw, sdg) published to GHCR. Currently, using these requires knowing the full image reference. The --from flag simplifies this to:

nemoclaw sandbox create --from openclaw

It also consolidates the two-step build+create workflow for custom Dockerfiles into a single command.

Proposed Behavior

--from accepts four input types, resolved in this order:

InputExampleResolution
Dockerfile path--from ./DockerfileBuild + push to cluster + create sandbox
Directory with Dockerfile--from ./my-sandbox/Build + push to cluster + create sandbox
Full image reference--from myregistry.com/img:tagUse directly as container image
Community sandbox name--from openclawResolve to ghcr.io/nvidia/nemoclaw-community/sandboxes/openclaw:latest

Resolution heuristic

  1. If it's an existing file with "Dockerfile" in the name → Dockerfile mode
  2. If it's an existing directory containing a DockerfileDockerfile mode (context = directory)
  3. If it contains /, :, or . → full image reference
  4. Otherwise → community sandbox name, resolved to {NEMOCLAW_COMMUNITY_REGISTRY}/{name}:latest

The community registry prefix defaults to ghcr.io/nvidia/nemoclaw-community/sandboxes and is overridable via NEMOCLAW_COMMUNITY_REGISTRY env var.

Policy handling

Policy remains separate — --from only resolves the image. Community sandbox images bake their policy into /etc/navigator/policy.yaml at build time. Users can still override with --policy.

Files to Change

  • crates/navigator-cli/src/main.rs — Replace --image with --from in SandboxCommands::Create
  • crates/navigator-cli/src/run.rs — Add resolve_from() helper, update sandbox_create() and sandbox_create_with_bootstrap() signatures, integrate build+push for Dockerfile sources
  • e2e/bash/test_sandbox_custom_image.sh — Update --image--from
  • architecture/sandbox-custom-containers.md — Document new --from flag and resolution modes

Acceptance Criteria

  • ncl sandbox create --from openclaw resolves to the community GHCR image and creates a sandbox
  • ncl sandbox create --from ./Dockerfile builds, pushes, and creates in one step
  • ncl sandbox create --from ./my-sandbox/ builds from directory context
  • ncl sandbox create --from myregistry.com/myimage:tag works like the old --image
  • --image flag is removed (replaced entirely by --from)
  • --from + --policy can be combined
  • NEMOCLAW_COMMUNITY_REGISTRY env var overrides the default community prefix
  • E2E test updated and passing
  • Architecture docs updated

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions