feat(cli): stage input files before starting a sandbox main command #4730

User Story

Follow-up to the concrete use case reported in #4301: an integrator runs an agent as an OpenShell sandbox's main command and needs to supply a large input file, such as a 30–100 KB system prompt, before that command starts. The run should retain main-command exit status reporting and --no-keep cleanup.

This issue tracks the remaining capability gap separately from the documentation correction in #4502. It carries forward the original reporter's use case; it does not claim a new reproduction or personal-use attestation from the filer.

Problem Statement

sandbox create --upload cannot be combined with a trailing command. Creation-time uploads currently finish after the canonical process starts, so removing the CLI conflict alone would not guarantee that an input file exists when the command reads it.

#4502 documents that restriction and corrects incompatible examples. It does not provide a creation-time file-input channel for a sandbox whose main process is the supplied command. Related input limits are tracked in #4291.

Impact / Why This Matters

Users can create a scratch sandbox, upload files, and run the workload with sandbox exec. However, the workload then runs as an exec command rather than the sandbox's main process; this changes lifecycle ownership and requires separate orchestration for cleanup.

Baking input into an image adds an image-build step for each changing input. Encoding input across arguments or environment values runs into size limits and puts input into command/configuration metadata.

The missing workflow is a per-run file transfer that completes before the main command starts, while preserving command-driven sandbox lifecycle behavior.

Proposed Design

Allow users to supply local input files during command-driven sandbox creation. Complete all requested uploads successfully before starting the supplied main command. If staging fails, do not run that command, and provide a clear failure and sandbox cleanup/recovery outcome.

Prefer extending the existing --upload workflow if feasible. The interaction below is illustrative; implementation and any API changes remain open for discussion.

Suggested UX

openshell sandbox create \
  --name prompt-run \
  --no-tty \
  --no-keep \
  --upload ./prompt.md:/tmp/prompt.md \
  -- sh -c 'cat /tmp/prompt.md'

The command should print the complete file, return the main command's exit status, and clean up the ephemeral sandbox after the command exits.

Acceptance Criteria

• A command-driven sandbox can receive a per-run local input file larger than a single argument's limit without encoding its contents into arguments or environment values.
• Every requested upload completes before the supplied main command starts.
• Upload failure prevents the supplied main command from running and yields a clear error with defined cleanup/recovery behavior.
• Main-command exit status reporting and --no-keep cleanup remain available.
• Documentation and relevant end-to-end coverage demonstrate successful staging, failed staging, and command completion/cleanup.

Alternatives Considered

• Scratch sandbox → upload → exec: supported workaround, but changes the main-process lifecycle and adds orchestration.
• Bake files into the sandbox image: suitable for static inputs, but requires rebuilding images for changing per-run inputs.
• Arguments/environment values: bounded and unsuitable as the general file-input channel.
• Providers, middleware, and gateway interceptors: useful for their existing credential/request workflows, but those workflows do not currently supply arbitrary local files with a before-main-command completion guarantee.

Agent Investigation

The CLI declares an argument conflict in crates/openshell-cli/src/main.rs. crates/openshell-cli/src/run.rs also rejects the combination explicitly because uploads complete after the canonical process starts, and transfers uploads after the sandbox reaches Ready. This requires lifecycle/staging work, not just removing argument validation.

Community Interest

If this would help your workflow, please react or comment with:

• What input you need to stage and its typical size.
• Which compute driver you use.
• Whether preserving the main command's lifecycle and automatic cleanup is necessary.
• Whether you would be interested in contributing a design or implementation.

This follow-up gathers demand and design input; it does not assume a roadmap commitment or implementation owner.