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?
Summary
Add a
cwsandbox runCLI command to create/start sandboxes from the terminal. This should cover the common "create a long-running sandbox, print its ID, then useexec,sh,logs,files,stop, ordeleteagainst it" workflow.Prefer
runas the primary command because the v1 API creates and starts a sandbox in one operation.createcan 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 --detachSuggested behavior:
--detach, create/start the sandbox, print the sandbox ID, and exit without stopping it.--detach, wait for the sandbox to become ready, stream main-process logs, and return the main process exit code when it completes.__exit__stops the sandbox.Sandbox.run(...),wait(),stream_logs(...), andwait_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-waitor--ready-timeout--detach--Additional resource, network, service, volume, template, and snapshot options can be follow-up work if needed.
Acceptance criteria
cwsandbox runis registered in the top-level CLI.create, it is documented as an alias for detached run semantics.exec,sh,logs, andstop.Open questions
createbe added now as a long alias, or should we keep the first version torunonly?Sandbox.detach()helper to make local cleanup explicit without stopping the remote sandbox, or is CLI-level handling enough?