Skip to content

feat(cli): add run/create command for sandbox creation #155

Description

@nicholaspun-wandb

Summary

Add a cwsandbox run CLI command to create/start sandboxes from the terminal. This should cover the common "create a long-running sandbox, print its ID, then use exec, sh, logs, files, stop, or delete against it" workflow.

Prefer run as the primary command because the v1 API creates and starts a sandbox in one operation. create can be considered as a compatibility/ergonomic alias for detached run, but it should not imply a stopped-created state.

Proposed UX

cwsandbox run [OPTIONS] [-- COMMAND [ARG]...]
cwsandbox run --detach [OPTIONS] [-- COMMAND [ARG]...]
cwsandbox create [OPTIONS] [-- COMMAND [ARG]...]  # optional alias for run --detach

Suggested behavior:

  • Without a command, use the SDK default keep-alive command.
  • With --detach, create/start the sandbox, print the sandbox ID, and exit without stopping it.
  • Without --detach, wait for the sandbox to become ready, stream main-process logs, and return the main process exit code when it completes.
  • Do not use the context-manager pattern for detached mode, since __exit__ stops the sandbox.
  • Use public SDK APIs such as Sandbox.run(...), wait(), stream_logs(...), and wait_until_complete(...); avoid direct generated-proto handling in CLI code.

Initial option scope

Start with common Sandbox.run(...) options rather than every SDK field:

  • --image
  • --tag
  • --env KEY=VALUE
  • --max-lifetime-seconds
  • --wait/--no-wait or --ready-timeout
  • --detach
  • command passthrough after --

Additional resource, network, service, volume, template, and snapshot options can be follow-up work if needed.

Acceptance criteria

  • cwsandbox run is registered in the top-level CLI.
  • If we add create, it is documented as an alias for detached run semantics.
  • Detached mode leaves the remote sandbox running and prints the sandbox ID.
  • Attached mode has clear wait/log behavior and exits with a useful status code.
  • Unit coverage verifies command registration, argument parsing, option-to-SDK mapping, and detached mode not stopping the sandbox.
  • The command is exercised against a live sandbox before release.
  • Documentation/examples show the intended flow with exec, sh, logs, and stop.

Open questions

  • Should create be added now as a long alias, or should we keep the first version to run only?
  • Should the default mode be attached or detached?
  • Do we need an SDK Sandbox.detach() helper to make local cleanup explicit without stopping the remote sandbox, or is CLI-level handling enough?

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Labels

enhancementNew feature or request

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions