docs(cli): sandbox create has undocumented 32768-byte arg, 8192-byte env and no-newline limits; point large inputs at --upload #4291

Version. OpenShell 0.1.2, Docker 29.7.2, macOS arm64. Observed 2026-09-29.

Observed. openshell sandbox create … -- <cmd> <args> is refused when:

• any command element exceeds 32768 bytes: Client specified an invalid argument: spec.command[16] exceeds 32768 byte limit
• any --env value exceeds 8192 bytes: spec.environment value exceeds maximum length (36160 > 8192)
• any --env value contains a newline: spec.environment contains newline or carriage return characters

None of the three limits is documented on the sandbox create page or in --help, and the CLI only reports them one at a time after a failed create.

Why it matters. Agent CLIs routinely take a system prompt of 30–100 KB as a single argument. Hitting all three limits at once, with no documentation, sends an integrator down the path of base64 + chunking across env vars and reassembling in sh inside the sandbox — which works, but is exactly the kind of workaround nobody should have to discover.

Repro.

openshell sandbox create --no-keep -- sh -c 'echo ok' "$(head -c 40000 /dev/zero | tr '\0' a)"

Ask.

1. Document the three limits on the sandbox create reference page and in --help.
2. Name the supported channel for a large input to a command-driven sandbox. Correction (2026-10-08): --upload is not it as of 0.1.2 — it is rejected together with a command (cannot be used with '[COMMAND]...', see bug(cli): --upload cannot be used together with a sandbox command, so a command-driven sandbox has no large-input channel #4301). It does work on a create with no command, so a two-phase create --upload + sandbox exec is the only route today; documenting that, or lifting the restriction, would close this.
3. Optionally, have the validator report all violated limits in one message.

Related: #24 introduced spec size limits; #3643 asks for the provider credential size limit to be configurable.