chore: remove deprecated --keep flag from docs, scripts, and e2e tests (#2126)

Ygnas · web-flow · commit a72711697ddd · 2026-07-07T14:36:25.000+02:00
* docs: remove deprecated --keep flag from tutorials and examples

The --keep flag is deprecated, hidden, and a no-op since sandboxes
are kept by default. Remove references from tutorial docs and example
READMEs that explain it as a real feature.

- Remove --keep from sandbox create commands
- Remove --keep explanation text
- Clarify that sandboxes are kept by default

Signed-off-by: Ignas Baranauskas &lt;ibaranau@redhat.com&gt;

* chore: remove deprecated --keep usage from scripts and e2e tests

The --keep flag is a deprecated no-op since sandboxes are kept by
default. Stop passing it in internal scripts, e2e test scripts,
and example demo scripts.

Signed-off-by: Ignas Baranauskas &lt;ibaranau@redhat.com&gt;

---------

Signed-off-by: Ignas Baranauskas &lt;ibaranau@redhat.com&gt;
diff --git a/docs/get-started/tutorials/first-network-policy.mdx b/docs/get-started/tutorials/first-network-policy.mdx
@@ -38,10 +38,10 @@ bash examples/sandbox-policy-quickstart/demo.sh
 Start by creating a sandbox with no network policies. This gives you a clean environment to observe default-deny behavior.
 
 ```shell
-openshell sandbox create --name demo --keep --no-auto-providers
+openshell sandbox create --name demo --no-auto-providers
 ```
 
-`--keep` keeps the sandbox running after you exit so you can reconnect later. `--no-auto-providers` skips the provider setup prompt since this tutorial uses `curl` instead of an AI agent.
+`--no-auto-providers` skips the provider setup prompt since this tutorial uses `curl` instead of an AI agent.
 
 You land in an interactive shell inside the sandbox:
 
@@ -65,7 +65,7 @@ The request fails. By default, all outbound network traffic is denied. The sandb
 curl: (56) Received HTTP code 403 from proxy after CONNECT
 ```
 
-Exit the sandbox. The `--keep` flag keeps it running:
+Exit the sandbox. Sandboxes are kept running by default, so you can reconnect later. Use `--no-keep` at creation time if you want the sandbox deleted after exit:
 
 ```shell
 exit
diff --git a/docs/get-started/tutorials/microsoft-graph-provider-refresh.mdx b/docs/get-started/tutorials/microsoft-graph-provider-refresh.mdx
@@ -160,7 +160,6 @@ Launch a sandbox with the Microsoft Graph provider attached:
 ```shell
 openshell sandbox create \
   --name microsoft-graph-mail \
-  --keep \
   --provider microsoft-mail \
   --no-auto-providers \
   -- /bin/sh
diff --git a/e2e/policy-advisor/mechanistic-smoke.sh b/e2e/policy-advisor/mechanistic-smoke.sh
@@ -78,7 +78,6 @@ create_sandbox() {
         --name "$SANDBOX" \
         --no-auto-providers \
         --no-tty \
-        --keep \
         -- bash -lc "echo sandbox ready" \
         | sed 's/^/  /'
 
diff --git a/e2e/policy-advisor/test.sh b/e2e/policy-advisor/test.sh
@@ -230,7 +230,6 @@ create_sandbox() {
         --policy "$POLICY_FILE" \
         --upload "${RUNNER_SOURCE}:/sandbox/policy-validation-runner.sh" \
         --no-git-ignore \
-        --keep \
         --no-auto-providers \
         --no-tty \
         -- bash -lc "chmod +x /sandbox/policy-validation-runner.sh && echo sandbox ready"
diff --git a/e2e/policy-advisor/wait-smoke.sh b/e2e/policy-advisor/wait-smoke.sh
@@ -128,7 +128,6 @@ create_sandbox() {
         --name "$SANDBOX" \
         --upload "${RUNNER_SOURCE}:/sandbox/runner.sh" \
         --no-git-ignore \
-        --keep \
         --no-auto-providers \
         --no-tty \
         -- bash -lc "chmod +x /sandbox/runner.sh && echo sandbox ready" \
diff --git a/examples/policy-advisor/README.md b/examples/policy-advisor/README.md
@@ -90,14 +90,12 @@ openshell sandbox create \
   --name advisor-ctf \
   --policy examples/policy-advisor/sandbox-policy.yaml \
   --upload examples/policy-advisor/ctf.py \
-  --keep \
   -- python3 -u /sandbox/ctf.py
 ```
 
 > **For agents running this CTF:** use the command above exactly.  The
-> `--upload` flag copies the script into `/sandbox/` before the command runs,
-> `--keep` prevents the sandbox from being torn down on exit, and `-u` gives
-> unbuffered output so you can see logs in real time.
+> `--upload` flag copies the script into `/sandbox/` before the command runs
+> and `-u` gives unbuffered output so you can see logs in real time.
 
 The script prints a banner and immediately tries Gate 1 (`httpbin.org:443`).
 It will fail with **"blocked by sandbox proxy"** and begin retrying every 10
diff --git a/examples/sandbox-policy-quickstart/README.md b/examples/sandbox-policy-quickstart/README.md
@@ -22,11 +22,10 @@ while writes are blocked — all without restarting anything.
 ### 1. Create a sandbox
 
 ```bash
-openshell sandbox create --name demo --keep --no-auto-providers
+openshell sandbox create --name demo --no-auto-providers
 ```
 
-`--keep` keeps the sandbox running after you exit so you can reconnect
-later. `--no-auto-providers` skips the provider setup prompt since this
+`--no-auto-providers` skips the provider setup prompt since this
 demo doesn't use an AI agent.
 
 You'll land in an interactive shell inside the sandbox:
@@ -50,7 +49,7 @@ The sandbox proxy intercepted the HTTPS CONNECT request to
 curl: (56) Received HTTP code 403 from proxy after CONNECT
 ```
 
-Exit the sandbox (the sandbox stays alive thanks to `--keep`):
+Exit the sandbox (sandboxes are kept running by default; pass `--no-keep` at creation time to delete on exit):
 
 ```bash
 exit
diff --git a/examples/sandbox-policy-quickstart/demo.sh b/examples/sandbox-policy-quickstart/demo.sh
@@ -86,7 +86,6 @@ wait_for_ssh() {
 step "1/7  Creating sandbox \"${SANDBOX_NAME}\" (default-deny networking)"
 run openshell sandbox create \
     --name "$SANDBOX_NAME" \
-    --keep \
     --no-auto-providers \
     --no-tty \
     -- echo "sandbox ready"
diff --git a/examples/spiffe-token-grant-demo/README.md b/examples/spiffe-token-grant-demo/README.md
@@ -74,7 +74,6 @@ openshell --gateway-endpoint "$GATEWAY" provider create \
 openshell --gateway-endpoint "$GATEWAY" sandbox create \
   --name spiffe-token-demo \
   --provider spiffe-token-demo \
-  --keep \
   --no-tty \
   -- echo "sandbox ready"
 
diff --git a/examples/spiffe-token-grant-demo/demo.sh b/examples/spiffe-token-grant-demo/demo.sh
@@ -115,7 +115,7 @@ run "${OS[@]}" settings set --global --key providers_v2_enabled --value true --y
 run "${OS[@]}" provider profile lint -f "$PROFILE_FILE"
 run "${OS[@]}" provider profile import -f "$PROFILE_FILE"
 run "${OS[@]}" provider create --name "$PROVIDER_NAME" --type "$PROFILE_ID" --runtime-credentials
-run "${OS[@]}" sandbox create --name "$SANDBOX_NAME" --provider "$PROVIDER_NAME" --keep --no-tty -- echo "sandbox ready"
+run "${OS[@]}" sandbox create --name "$SANDBOX_NAME" --provider "$PROVIDER_NAME" --no-tty -- echo "sandbox ready"
 
 sandbox_curl_until "alpha" "http://alpha.default.svc.cluster.local/" "alpha called with path /:"
 ALPHA_OUTPUT="$SANDBOX_CURL_OUTPUT"
diff --git a/scripts/agents/gator/README.md b/scripts/agents/gator/README.md
@@ -42,8 +42,6 @@ The launcher:
 - For `--harness codex`, optionally bakes a host Codex executable as `/etc/openshell/agent-payload/runtime/harnesses/codex/codex`.
 - Starts the selected harness without a TTY.
 - Runs gator in `watch` mode by default. The sandbox stays alive while the supervisor sleeps between bounded Codex cycles, so Codex is not connected during passive PR waits. The supervisor prints periodic heartbeat lines during active cycles and passive sleeps.
-- Deletes the sandbox automatically after the supervisor exits. Pass `--keep` to preserve it for debugging.
-
 The GitHub provider profile allows read-only GraphQL queries on `api.github.com/graphql` so `gh` read paths can use GraphQL when needed. Write operations remain REST-only and scoped to the two allowed repositories.
 
 Set `GATOR_CODEX_ACCESS_CREDENTIAL_KEY` or pass `--codex-access-key` if the gator Codex profile uses a credential key other than `CODEX_AUTH_ACCESS_TOKEN` for the short-lived access token.
diff --git a/scripts/smoke-test-network-policy.sh b/scripts/smoke-test-network-policy.sh
@@ -131,14 +131,14 @@ write_policy() {
     echo "$file"
 }
 
-# Create a sandbox with --keep and a sleep, wait for Ready.
+# Create a sandbox with a sleep, wait for Ready (sandboxes are kept by default).
 create_sandbox() {
     local name="$1"
     shift
     local provider_flag=("$@")
 
     echo "  Creating sandbox: $name"
-    openshell sandbox create --name "$name" --keep "${provider_flag[@]}" \
+    openshell sandbox create --name "$name" "${provider_flag[@]}" \
         -- sh -c "echo Ready && sleep 3600" >/dev/null 2>&1 &
     local pid=$!
 
@@ -147,7 +147,7 @@ create_sandbox() {
         if openshell sandbox list 2>/dev/null | grep -q "$name.*Ready"; then
             echo "  Sandbox $name is Ready"
             SANDBOXES+=("$name")
-            # Kill the blocking create process (sandbox stays alive with --keep)
+            # Kill the blocking create process (sandbox stays alive by default)
             kill "$pid" 2>/dev/null || true
             wait "$pid" 2>/dev/null || true
             # Brief settle time — SSH server inside the sandbox may still be
diff --git a/tasks/scripts/vm/smoke-orphan-cleanup.sh b/tasks/scripts/vm/smoke-orphan-cleanup.sh
@@ -93,15 +93,15 @@ EOF
 }
 
 create_sandbox() {
-    echo "==> Creating sandbox (--keep, long-running)"
+    echo "==> Creating sandbox (long-running)"
     mkdir -p "$XDG"
     XDG_CONFIG_HOME="$XDG" "$ROOT/scripts/bin/openshell" gateway add \
         --name vm-orphan http://127.0.0.1:"$PORT" >/dev/null
     XDG_CONFIG_HOME="$XDG" "$ROOT/scripts/bin/openshell" gateway select vm-orphan >/dev/null
 
     # Run the CLI in the background; it blocks waiting for sleep to finish.
     XDG_CONFIG_HOME="$XDG" "$ROOT/scripts/bin/openshell" sandbox create \
-        --name "orphan-$$" --keep -- sleep 99999 \
+        --name "orphan-$$" -- sleep 99999 \
         > "$LOG.create" 2>&1 &
     CLI_PID=$!
 
