From 7fc7dcfa479199a52c4f9e8e98781ff99c3f67df Mon Sep 17 00:00:00 2001 From: Kris Hicks Date: Mon, 3 Aug 2026 14:58:12 -0700 Subject: [PATCH] docs(cli): recommend providers for secrets Update the docs for `sandbox create` and `exec` to dissuade use of `--env` for secrets, and enhance the docs for `--provider` to explain what it's for. Signed-off-by: Kris Hicks --- .agents/skills/openshell-cli/SKILL.md | 6 ++++-- crates/openshell-cli/src/main.rs | 12 +++++++++--- 2 files changed, 13 insertions(+), 5 deletions(-) diff --git a/.agents/skills/openshell-cli/SKILL.md b/.agents/skills/openshell-cli/SKILL.md index 213d55216f..91136340fc 100644 --- a/.agents/skills/openshell-cli/SKILL.md +++ b/.agents/skills/openshell-cli/SKILL.md @@ -183,13 +183,13 @@ openshell sandbox create \ ``` Key flags: -- `--provider`: Attach one or more providers (repeatable) +- `--provider`: Attach configured credential providers for API keys, tokens, and other secrets (repeatable) - `--policy`: Custom policy YAML (otherwise uses built-in default or `OPENSHELL_SANDBOX_POLICY` env var) - `--gpu [COUNT]`: Request the driver's default GPU selection or a specific GPU count - `--cpu`, `--memory`: Set per-sandbox compute sizing. Docker/Podman apply limits; Kubernetes applies matching requests and limits. - `--driver-config-json`: Pass experimental driver-specific sandbox configuration - `--label KEY=VALUE`: Add labels for later selection (repeatable) -- `--env KEY=VALUE`: Inject sandbox environment variables (repeatable) +- `--env KEY=VALUE`: Set non-secret sandbox environment variables (repeatable); use `--provider` for credentials - `--approval-mode manual|auto`: Control handling of agent-authored policy proposals; `manual` is the default - `--upload [:]`: Upload local files into the container working directory or an explicit destination - `--no-git-ignore`: Disable `.gitignore` filtering for uploads @@ -242,6 +242,8 @@ openshell sandbox exec --name my-sandbox --env MODE=test -- cargo test ``` `sandbox exec` streams output and exits with the remote command's exit code. Use `sandbox connect` for an interactive shell. +Use `--env` only for non-secret values. Attach credentials to the sandbox with a +provider instead of passing API keys, tokens, or other secrets to `sandbox exec`. ### Change attached providers diff --git a/crates/openshell-cli/src/main.rs b/crates/openshell-cli/src/main.rs index b541d350ec..4ea2765d25 100644 --- a/crates/openshell-cli/src/main.rs +++ b/crates/openshell-cli/src/main.rs @@ -1391,7 +1391,9 @@ enum SandboxCommands { #[arg(long, value_name = "JSON")] driver_config_json: Option, - /// Provider names to attach to this sandbox. + /// Attach a configured credential provider to the sandbox. + /// Use providers for API keys, tokens, and other secrets so commands in + /// the sandbox do not receive the real credential values. Repeatable. #[arg(long = "provider")] providers: Vec, @@ -1431,7 +1433,9 @@ enum SandboxCommands { #[arg(long = "label")] labels: Vec, - /// Environment variables to inject into the sandbox (KEY=VALUE format, repeatable). + /// 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. #[arg(long = "env", value_name = "KEY=VALUE")] envs: Vec, @@ -1553,7 +1557,9 @@ enum SandboxCommands { #[arg(long, overrides_with = "tty")] no_tty: bool, - /// Environment variables to set for the command (KEY=VALUE format, repeatable). + /// Set a non-secret environment variable for the command. + /// Do not use this option for API keys, tokens, or other secrets; attach + /// a provider to the sandbox instead. Repeatable. #[arg(long = "env", value_name = "KEY=VALUE")] envs: Vec,