diff --git a/crates/openshell-cli/src/main.rs b/crates/openshell-cli/src/main.rs
index b02ca31e3..067f4ddcf 100644
--- a/crates/openshell-cli/src/main.rs
+++ b/crates/openshell-cli/src/main.rs
@@ -1593,6 +1593,7 @@ enum SandboxCommands {
         /// Set a non-secret environment variable in the sandbox.
         /// Do not use this option for API keys, tokens, or other secrets; create
         /// a provider and attach it with `--provider` instead. Repeatable.
+        /// Each value is limited to 8 KiB and cannot contain a newline.
         #[arg(long = "env", value_name = "KEY=VALUE")]
         envs: Vec<String>,
 
@@ -1617,6 +1618,7 @@ enum SandboxCommands {
         output: OutputFormat,
 
         /// Command to run after "--" (defaults to an interactive shell).
+        /// Each argument is limited to 32 KiB.
         #[arg(last = true, allow_hyphen_values = true)]
         command: Vec<String>,
     },
diff --git a/docs/how-it-works/sandboxes/overview.mdx b/docs/how-it-works/sandboxes/overview.mdx
index bcff5001a..c3f6f86dc 100644
--- a/docs/how-it-works/sandboxes/overview.mdx
+++ b/docs/how-it-works/sandboxes/overview.mdx
@@ -76,6 +76,10 @@ finish after the canonical process starts. Create a scratch sandbox, upload the
 files, then launch the workload with `sandbox exec`, or build the files into the
 sandbox image.
 
+The trailing command takes at most 256 arguments. Each argument is limited to
+32 KiB and all arguments together to 256 KiB. Send a larger input, such as a
+long system prompt, with `sandbox upload` and read it inside the sandbox.
+
 For automation, use `--output json` or `--output yaml` to get machine-readable sandbox metadata after creation:
 
 ```shell
@@ -401,6 +405,10 @@ Per-command variables override the sandbox-level environment for that command on
 
 Environment variable names starting with `OPENSHELL_` are reserved. Keys must match `[A-Za-z_][A-Za-z0-9_]*`.
 
+`sandbox create` accepts at most 128 variables. Each value is limited to 8 KiB
+and cannot contain a newline, and all names and values together are limited to
+256 KiB. Send larger or multi-line values with `sandbox upload`.
+
 ## Label a Sandbox
 
 Attach labels when you create a sandbox to track ownership, environment, or workflow grouping: