chore: vendor sbx v0.39.0 cli reference

Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>

data/sbx_cli/sbx.yaml

@@ -4,7 +4,7 @@ description: |-
     Docker Sandboxes creates isolated sandbox environments for AI agents, powered by Docker.
 
     Run without a command to launch interactive mode, or pass a command for CLI usage.
-usage: sbx
+usage: sbx COMMAND
 options:
     - name: debug
       shorthand: D
@@ -20,6 +20,7 @@ see_also:
     - sbx create - Create a sandbox for an agent
     - sbx daemon - Manage sandboxd daemon
     - sbx diagnose - Diagnose common issues with your sbx installation
+    - sbx env - (Experimental) Manage sandboxes declaratively from a .sbxenv.yaml file
     - sbx exec - Execute a command inside a sandbox
     - sbx kit - (Experimental) Manage kit artifacts
     - sbx login - Sign in to Docker
@@ -28,6 +29,7 @@ see_also:
     - sbx mcp - Manage MCP servers
     - sbx policy - Manage sandbox policies
     - sbx ports - Manage sandbox port publishing
+    - sbx prune - Remove all stopped sandboxes
     - sbx reset - Reset all sandboxes and clean up state
     - sbx rm - Remove one or more sandboxes
     - sbx run - Run an agent in a sandbox

data/sbx_cli/sbx_completion.yaml

@@ -3,6 +3,7 @@ synopsis: Generate the autocompletion script for the specified shell
 description: |
     Generate the autocompletion script for sbx for the specified shell.
     See each sub-command's help for details on how to use the generated script.
+usage: sbx completion COMMAND
 options:
     - name: help
       shorthand: h

data/sbx_cli/sbx_create.yaml

@@ -18,6 +18,15 @@ options:
       default_value: '[]'
       usage: |
         Add a per-sandbox network deny rule at creation time. Can be specified multiple times. The rule applies only to the new sandbox and can be listed or removed later with `sbx policy ls <NAME>` / `sbx policy rm network --sandbox <NAME> --resource <HOST>`. Safe under centralized governance because a local deny can only narrow, never widen, egress.
+    - name: env
+      shorthand: e
+      default_value: '[]'
+      usage: |
+        Set an environment variable in the sandbox (can be repeated): KEY=VALUE, or a bare KEY to take the value from the current environment
+    - name: env-file
+      default_value: '[]'
+      usage: |
+        Read environment variables from a file (can be repeated). --env wins over any file; a later file wins over an earlier one
     - name: help
       shorthand: h
       default_value: "false"
@@ -33,7 +42,7 @@ options:
         Memory limit in binary units (e.g., 1024m, 8g). Default: 50% of host memory, max 32 GiB
     - name: name
       usage: |
-        Name for the sandbox (default: <agent>-<workdir>, letters, numbers, hyphens, periods, plus signs and minus signs only)
+        Name for the sandbox (defaults to <agent>-<workdir>; at least two characters, starting with a letter or number, containing only letters, numbers, hyphens and periods; 'default' is reserved)
     - name: publish
       shorthand: p
       default_value: '[]'

data/sbx_cli/sbx_create_claude.yaml

@@ -31,6 +31,15 @@ inherited_options:
       default_value: '[]'
       usage: |
         Add a per-sandbox network deny rule at creation time. Can be specified multiple times. The rule applies only to the new sandbox and can be listed or removed later with `sbx policy ls <NAME>` / `sbx policy rm network --sandbox <NAME> --resource <HOST>`. Safe under centralized governance because a local deny can only narrow, never widen, egress.
+    - name: env
+      shorthand: e
+      default_value: '[]'
+      usage: |
+        Set an environment variable in the sandbox (can be repeated): KEY=VALUE, or a bare KEY to take the value from the current environment
+    - name: env-file
+      default_value: '[]'
+      usage: |
+        Read environment variables from a file (can be repeated). --env wins over any file; a later file wins over an earlier one
     - name: kit
       default_value: '[]'
       experimental: true
@@ -42,7 +51,7 @@ inherited_options:
         Memory limit in binary units (e.g., 1024m, 8g). Default: 50% of host memory, max 32 GiB
     - name: name
       usage: |
-        Name for the sandbox (default: <agent>-<workdir>, letters, numbers, hyphens, periods, plus signs and minus signs only)
+        Name for the sandbox (defaults to <agent>-<workdir>; at least two characters, starting with a letter or number, containing only letters, numbers, hyphens and periods; 'default' is reserved)
     - name: publish
       shorthand: p
       default_value: '[]'

data/sbx_cli/sbx_create_codex.yaml

@@ -31,6 +31,15 @@ inherited_options:
       default_value: '[]'
       usage: |
         Add a per-sandbox network deny rule at creation time. Can be specified multiple times. The rule applies only to the new sandbox and can be listed or removed later with `sbx policy ls <NAME>` / `sbx policy rm network --sandbox <NAME> --resource <HOST>`. Safe under centralized governance because a local deny can only narrow, never widen, egress.
+    - name: env
+      shorthand: e
+      default_value: '[]'
+      usage: |
+        Set an environment variable in the sandbox (can be repeated): KEY=VALUE, or a bare KEY to take the value from the current environment
+    - name: env-file
+      default_value: '[]'
+      usage: |
+        Read environment variables from a file (can be repeated). --env wins over any file; a later file wins over an earlier one
     - name: kit
       default_value: '[]'
       experimental: true
@@ -42,7 +51,7 @@ inherited_options:
         Memory limit in binary units (e.g., 1024m, 8g). Default: 50% of host memory, max 32 GiB
     - name: name
       usage: |
-        Name for the sandbox (default: <agent>-<workdir>, letters, numbers, hyphens, periods, plus signs and minus signs only)
+        Name for the sandbox (defaults to <agent>-<workdir>; at least two characters, starting with a letter or number, containing only letters, numbers, hyphens and periods; 'default' is reserved)
     - name: publish
       shorthand: p
       default_value: '[]'

data/sbx_cli/sbx_create_copilot.yaml

@@ -31,6 +31,15 @@ inherited_options:
       default_value: '[]'
       usage: |
         Add a per-sandbox network deny rule at creation time. Can be specified multiple times. The rule applies only to the new sandbox and can be listed or removed later with `sbx policy ls <NAME>` / `sbx policy rm network --sandbox <NAME> --resource <HOST>`. Safe under centralized governance because a local deny can only narrow, never widen, egress.
+    - name: env
+      shorthand: e
+      default_value: '[]'
+      usage: |
+        Set an environment variable in the sandbox (can be repeated): KEY=VALUE, or a bare KEY to take the value from the current environment
+    - name: env-file
+      default_value: '[]'
+      usage: |
+        Read environment variables from a file (can be repeated). --env wins over any file; a later file wins over an earlier one
     - name: kit
       default_value: '[]'
       experimental: true
@@ -42,7 +51,7 @@ inherited_options:
         Memory limit in binary units (e.g., 1024m, 8g). Default: 50% of host memory, max 32 GiB
     - name: name
       usage: |
-        Name for the sandbox (default: <agent>-<workdir>, letters, numbers, hyphens, periods, plus signs and minus signs only)
+        Name for the sandbox (defaults to <agent>-<workdir>; at least two characters, starting with a letter or number, containing only letters, numbers, hyphens and periods; 'default' is reserved)
     - name: publish
       shorthand: p
       default_value: '[]'

data/sbx_cli/sbx_create_cursor.yaml

@@ -31,6 +31,15 @@ inherited_options:
       default_value: '[]'
       usage: |
         Add a per-sandbox network deny rule at creation time. Can be specified multiple times. The rule applies only to the new sandbox and can be listed or removed later with `sbx policy ls <NAME>` / `sbx policy rm network --sandbox <NAME> --resource <HOST>`. Safe under centralized governance because a local deny can only narrow, never widen, egress.
+    - name: env
+      shorthand: e
+      default_value: '[]'
+      usage: |
+        Set an environment variable in the sandbox (can be repeated): KEY=VALUE, or a bare KEY to take the value from the current environment
+    - name: env-file
+      default_value: '[]'
+      usage: |
+        Read environment variables from a file (can be repeated). --env wins over any file; a later file wins over an earlier one
     - name: kit
       default_value: '[]'
       experimental: true
@@ -42,7 +51,7 @@ inherited_options:
         Memory limit in binary units (e.g., 1024m, 8g). Default: 50% of host memory, max 32 GiB
     - name: name
       usage: |
-        Name for the sandbox (default: <agent>-<workdir>, letters, numbers, hyphens, periods, plus signs and minus signs only)
+        Name for the sandbox (defaults to <agent>-<workdir>; at least two characters, starting with a letter or number, containing only letters, numbers, hyphens and periods; 'default' is reserved)
     - name: publish
       shorthand: p
       default_value: '[]'

data/sbx_cli/sbx_create_docker-agent.yaml

@@ -31,6 +31,15 @@ inherited_options:
       default_value: '[]'
       usage: |
         Add a per-sandbox network deny rule at creation time. Can be specified multiple times. The rule applies only to the new sandbox and can be listed or removed later with `sbx policy ls <NAME>` / `sbx policy rm network --sandbox <NAME> --resource <HOST>`. Safe under centralized governance because a local deny can only narrow, never widen, egress.
+    - name: env
+      shorthand: e
+      default_value: '[]'
+      usage: |
+        Set an environment variable in the sandbox (can be repeated): KEY=VALUE, or a bare KEY to take the value from the current environment
+    - name: env-file
+      default_value: '[]'
+      usage: |
+        Read environment variables from a file (can be repeated). --env wins over any file; a later file wins over an earlier one
     - name: kit
       default_value: '[]'
       experimental: true
@@ -42,7 +51,7 @@ inherited_options:
         Memory limit in binary units (e.g., 1024m, 8g). Default: 50% of host memory, max 32 GiB
     - name: name
       usage: |
-        Name for the sandbox (default: <agent>-<workdir>, letters, numbers, hyphens, periods, plus signs and minus signs only)
+        Name for the sandbox (defaults to <agent>-<workdir>; at least two characters, starting with a letter or number, containing only letters, numbers, hyphens and periods; 'default' is reserved)
     - name: publish
       shorthand: p
       default_value: '[]'

data/sbx_cli/sbx_create_droid.yaml

@@ -31,6 +31,15 @@ inherited_options:
       default_value: '[]'
       usage: |
         Add a per-sandbox network deny rule at creation time. Can be specified multiple times. The rule applies only to the new sandbox and can be listed or removed later with `sbx policy ls <NAME>` / `sbx policy rm network --sandbox <NAME> --resource <HOST>`. Safe under centralized governance because a local deny can only narrow, never widen, egress.
+    - name: env
+      shorthand: e
+      default_value: '[]'
+      usage: |
+        Set an environment variable in the sandbox (can be repeated): KEY=VALUE, or a bare KEY to take the value from the current environment
+    - name: env-file
+      default_value: '[]'
+      usage: |
+        Read environment variables from a file (can be repeated). --env wins over any file; a later file wins over an earlier one
     - name: kit
       default_value: '[]'
       experimental: true
@@ -42,7 +51,7 @@ inherited_options:
         Memory limit in binary units (e.g., 1024m, 8g). Default: 50% of host memory, max 32 GiB
     - name: name
       usage: |
-        Name for the sandbox (default: <agent>-<workdir>, letters, numbers, hyphens, periods, plus signs and minus signs only)
+        Name for the sandbox (defaults to <agent>-<workdir>; at least two characters, starting with a letter or number, containing only letters, numbers, hyphens and periods; 'default' is reserved)
     - name: publish
       shorthand: p
       default_value: '[]'

data/sbx_cli/sbx_create_gemini.yaml

@@ -31,6 +31,15 @@ inherited_options:
       default_value: '[]'
       usage: |
         Add a per-sandbox network deny rule at creation time. Can be specified multiple times. The rule applies only to the new sandbox and can be listed or removed later with `sbx policy ls <NAME>` / `sbx policy rm network --sandbox <NAME> --resource <HOST>`. Safe under centralized governance because a local deny can only narrow, never widen, egress.
+    - name: env
+      shorthand: e
+      default_value: '[]'
+      usage: |
+        Set an environment variable in the sandbox (can be repeated): KEY=VALUE, or a bare KEY to take the value from the current environment
+    - name: env-file
+      default_value: '[]'
+      usage: |
+        Read environment variables from a file (can be repeated). --env wins over any file; a later file wins over an earlier one
     - name: kit
       default_value: '[]'
       experimental: true
@@ -42,7 +51,7 @@ inherited_options:
         Memory limit in binary units (e.g., 1024m, 8g). Default: 50% of host memory, max 32 GiB
     - name: name
       usage: |
-        Name for the sandbox (default: <agent>-<workdir>, letters, numbers, hyphens, periods, plus signs and minus signs only)
+        Name for the sandbox (defaults to <agent>-<workdir>; at least two characters, starting with a letter or number, containing only letters, numbers, hyphens and periods; 'default' is reserved)
     - name: publish
       shorthand: p
       default_value: '[]'

data/sbx_cli/sbx_create_kiro.yaml

@@ -31,6 +31,15 @@ inherited_options:
       default_value: '[]'
       usage: |
         Add a per-sandbox network deny rule at creation time. Can be specified multiple times. The rule applies only to the new sandbox and can be listed or removed later with `sbx policy ls <NAME>` / `sbx policy rm network --sandbox <NAME> --resource <HOST>`. Safe under centralized governance because a local deny can only narrow, never widen, egress.
+    - name: env
+      shorthand: e
+      default_value: '[]'
+      usage: |
+        Set an environment variable in the sandbox (can be repeated): KEY=VALUE, or a bare KEY to take the value from the current environment
+    - name: env-file
+      default_value: '[]'
+      usage: |
+        Read environment variables from a file (can be repeated). --env wins over any file; a later file wins over an earlier one
     - name: kit
       default_value: '[]'
       experimental: true
@@ -42,7 +51,7 @@ inherited_options:
         Memory limit in binary units (e.g., 1024m, 8g). Default: 50% of host memory, max 32 GiB
     - name: name
       usage: |
-        Name for the sandbox (default: <agent>-<workdir>, letters, numbers, hyphens, periods, plus signs and minus signs only)
+        Name for the sandbox (defaults to <agent>-<workdir>; at least two characters, starting with a letter or number, containing only letters, numbers, hyphens and periods; 'default' is reserved)
     - name: publish
       shorthand: p
       default_value: '[]'

data/sbx_cli/sbx_create_opencode.yaml

@@ -31,6 +31,15 @@ inherited_options:
       default_value: '[]'
       usage: |
         Add a per-sandbox network deny rule at creation time. Can be specified multiple times. The rule applies only to the new sandbox and can be listed or removed later with `sbx policy ls <NAME>` / `sbx policy rm network --sandbox <NAME> --resource <HOST>`. Safe under centralized governance because a local deny can only narrow, never widen, egress.
+    - name: env
+      shorthand: e
+      default_value: '[]'
+      usage: |
+        Set an environment variable in the sandbox (can be repeated): KEY=VALUE, or a bare KEY to take the value from the current environment
+    - name: env-file
+      default_value: '[]'
+      usage: |
+        Read environment variables from a file (can be repeated). --env wins over any file; a later file wins over an earlier one
     - name: kit
       default_value: '[]'
       experimental: true
@@ -42,7 +51,7 @@ inherited_options:
         Memory limit in binary units (e.g., 1024m, 8g). Default: 50% of host memory, max 32 GiB
     - name: name
       usage: |
-        Name for the sandbox (default: <agent>-<workdir>, letters, numbers, hyphens, periods, plus signs and minus signs only)
+        Name for the sandbox (defaults to <agent>-<workdir>; at least two characters, starting with a letter or number, containing only letters, numbers, hyphens and periods; 'default' is reserved)
     - name: publish
       shorthand: p
       default_value: '[]'

data/sbx_cli/sbx_create_shell.yaml

@@ -31,6 +31,15 @@ inherited_options:
       default_value: '[]'
       usage: |
         Add a per-sandbox network deny rule at creation time. Can be specified multiple times. The rule applies only to the new sandbox and can be listed or removed later with `sbx policy ls <NAME>` / `sbx policy rm network --sandbox <NAME> --resource <HOST>`. Safe under centralized governance because a local deny can only narrow, never widen, egress.
+    - name: env
+      shorthand: e
+      default_value: '[]'
+      usage: |
+        Set an environment variable in the sandbox (can be repeated): KEY=VALUE, or a bare KEY to take the value from the current environment
+    - name: env-file
+      default_value: '[]'
+      usage: |
+        Read environment variables from a file (can be repeated). --env wins over any file; a later file wins over an earlier one
     - name: kit
       default_value: '[]'
       experimental: true
@@ -42,7 +51,7 @@ inherited_options:
         Memory limit in binary units (e.g., 1024m, 8g). Default: 50% of host memory, max 32 GiB
     - name: name
       usage: |
-        Name for the sandbox (default: <agent>-<workdir>, letters, numbers, hyphens, periods, plus signs and minus signs only)
+        Name for the sandbox (defaults to <agent>-<workdir>; at least two characters, starting with a letter or number, containing only letters, numbers, hyphens and periods; 'default' is reserved)
     - name: publish
       shorthand: p
       default_value: '[]'

data/sbx_cli/sbx_daemon.yaml

@@ -1,5 +1,6 @@
 name: sbx daemon
 synopsis: Manage sandboxd daemon
+usage: sbx daemon COMMAND
 options:
     - name: help
       shorthand: h

data/sbx_cli/sbx_daemon_log-level.yaml

@@ -1,6 +1,6 @@
 name: sbx daemon log-level
 synopsis: Inspect or change sandboxd's per-category log levels
-usage: sbx daemon log-level [flags]
+usage: sbx daemon log-level [COMMAND]
 options:
     - name: help
       shorthand: h

data/sbx_cli/sbx_kit.yaml

@@ -22,6 +22,9 @@ see_also:
     - sbx kit add - Add a kit to a sandbox
     - sbx kit inspect - Display details about a kit artifact
     - sbx kit pack - Package a directory as a kit artifact
+    - sbx kit provenance - Show the SLSA provenance attached to a kit
     - sbx kit pull - Pull a kit artifact from an OCI registry
     - sbx kit push - Push a kit artifact to an OCI registry
+    - sbx kit sign - Sign a kit artifact
     - sbx kit validate - Validate a kit artifact
+    - sbx kit verify - Verify a kit artifact's signature

data/sbx_cli/sbx_kit_provenance.yaml

@@ -0,0 +1,53 @@
+name: sbx kit provenance
+synopsis: Show the SLSA provenance attached to a kit
+experimental: true
+description: |-
+    Print the SLSA provenance attestation attached to an OCI kit.
+
+    Provenance is attached by `sbx kit push` as an OCI referrer of the kit
+    manifest. It records the kit's content digests, the sandbox image its spec
+    declares, and the source git commit the kit was pushed from.
+
+    Provenance pushed without --sign is unsigned: it is printed but marked
+    UNSIGNED, because anyone with push access to the repository could have
+    written it. To verify a signed attestation, pass --key for a key-based
+    signature, or --certificate-identity (or --certificate-identity-regexp)
+    together with --certificate-oidc-issuer (or its regexp form) for a keyless
+    one; only attestations that verify and whose subject matches the kit's own
+    digest are reported as VERIFIED.
+usage: sbx kit provenance REFERENCE [flags]
+options:
+    - name: certificate-identity
+      usage: Exact keyless signer identity (certificate SAN)
+    - name: certificate-identity-regexp
+      usage: Keyless signer identity regexp (certificate SAN)
+    - name: certificate-oidc-issuer
+      usage: Exact keyless OIDC issuer
+    - name: certificate-oidc-issuer-regexp
+      usage: Keyless OIDC issuer regexp
+    - name: help
+      shorthand: h
+      default_value: "false"
+      usage: help for provenance
+    - name: insecure-ignore-tlog
+      default_value: "false"
+      usage: |
+        Do not require a Rekor transparency-log entry (for private keyless signatures)
+    - name: key
+      usage: Public key for key-based verification (PEM)
+inherited_options:
+    - name: debug
+      shorthand: D
+      default_value: "false"
+      usage: Enable debug logging
+example: |4-
+      # Show provenance (unsigned attestations are printed as-is)
+      sbx kit provenance ghcr.io/org/my-kit:1.0
+
+      # Verify a signed attestation before printing it
+      sbx kit provenance \
+        --certificate-identity user@example.com \
+        --certificate-oidc-issuer https://accounts.google.com \
+        ghcr.io/org/my-kit:1.0
+see_also:
+    - sbx kit - (Experimental) Manage kit artifacts

data/sbx_cli/sbx_kit_push.yaml

@@ -14,6 +14,16 @@ description: |-
                             distribution tooling can read kit metadata
                             without pulling layers)
 
+    With --sign, the pushed manifest is signed and the Sigstore bundle is
+    attached to the kit as an OCI referrer. Signing is keyless (Fulcio +
+    Rekor) unless --key is given for key-based signing.
+
+    Every push also attaches a SLSA provenance attestation as an OCI
+    referrer, recording the kit's content digests, the declared sandbox
+    image, and the source git commit when the directory is a working tree.
+    The provenance is unsigned unless --sign is given, in which case it is
+    signed as a DSSE in-toto attestation with the same identity or key.
+
     Authentication uses the Docker credential store.
 usage: sbx kit push DIRECTORY REFERENCE [flags]
 options:
@@ -21,6 +31,23 @@ options:
       shorthand: h
       default_value: "false"
       usage: help for push
+    - name: identity-token
+      usage: |
+        OIDC identity token for keyless signing; defaults to the ambient CI provider, then an interactive browser login
+    - name: identity-token-file
+      usage: |
+        File holding the OIDC identity token; keeps it out of the process arguments
+    - name: key
+      usage: |
+        Private key for key-based signing (PEM); omit for keyless signing
+    - name: sign
+      default_value: "false"
+      usage: |
+        Sign the pushed kit and attach the signature as an OCI referrer
+    - name: tlog-upload
+      default_value: "true"
+      usage: |
+        Upload the keyless signature to the Rekor transparency log; set false for private kits
 inherited_options:
     - name: debug
       shorthand: D

data/sbx_cli/sbx_kit_sign.yaml

@@ -0,0 +1,62 @@
+name: sbx kit sign
+synopsis: Sign a kit artifact
+experimental: true
+description: |-
+    Sign a kit artifact with cosign-compatible Sigstore signatures.
+
+    For a local directory, a detached signature bundle is written to
+    kit.sig.bundle next to spec.yaml. For an OCI reference, the
+    signature is attached to the kit manifest as an OCI referrer.
+
+    Signing is keyless by default (Fulcio + Rekor), which requires an OIDC
+    identity token. In CI the token is minted automatically by the detected
+    platform (GitHub Actions, Buildkite, GCP, SPIFFE, or a projected
+    service-account token on disk). Elsewhere, supply one with
+    --identity-token-file or --identity-token, or complete an interactive
+    browser login. Prefer the file form: process arguments are readable by
+    other local users and are recorded in shell history. A token is never
+    read from SIGSTORE_ID_TOKEN, so it cannot be chosen by anything that can
+    set an environment variable. Use --key for key-based signing with an
+    unencrypted PEM private key.
+
+    For private kits whose signing event must not leak to a public log, pass
+    --tlog-upload=false to skip the Rekor transparency log. This only affects
+    keyless signing (key-based signing never uploads to Rekor) and requires
+    the signing config to provide a timestamp authority so the signature stays
+    verifiable after the short-lived certificate expires. For fully offline,
+    private signing, prefer key-based signing with --key.
+usage: sbx kit sign REFERENCE [flags]
+options:
+    - name: help
+      shorthand: h
+      default_value: "false"
+      usage: help for sign
+    - name: identity-token
+      usage: |
+        OIDC identity token for keyless signing; defaults to the ambient CI provider, then an interactive browser login
+    - name: identity-token-file
+      usage: |
+        File holding the OIDC identity token; keeps it out of the process arguments
+    - name: key
+      usage: |
+        Private key for key-based signing (PEM); omit for keyless signing
+    - name: tlog-upload
+      default_value: "true"
+      usage: |
+        Upload the keyless signature to the Rekor transparency log; set false for private kits
+inherited_options:
+    - name: debug
+      shorthand: D
+      default_value: "false"
+      usage: Enable debug logging
+example: |4-
+      # Keyless-sign a local kit directory
+      sbx kit sign ./my-kit/
+
+      # Key-based sign an OCI kit
+      sbx kit sign --key cosign.key ghcr.io/org/my-kit:1.0
+
+      # Keyless-sign without uploading to the public transparency log
+      sbx kit sign --tlog-upload=false ghcr.io/org/private-kit:1.0
+see_also:
+    - sbx kit - (Experimental) Manage kit artifacts

data/sbx_cli/sbx_kit_verify.yaml

@@ -0,0 +1,57 @@
+name: sbx kit verify
+synopsis: Verify a kit artifact's signature
+experimental: true
+description: |-
+    Verify a kit artifact's cosign-compatible signature.
+
+    For a local directory, the kit.sig.bundle sidecar is checked
+    against the kit's content. For a git reference, the repository is cloned and
+    its committed kit.sig.bundle sidecar is checked the same way.
+    For an OCI reference, signatures attached as OCI referrers are checked against
+    the kit manifest.
+
+    Use --key to verify a key-based signature against a PEM public key. For
+    keyless signatures, supply the accepted signer identity with
+    --certificate-identity (or --certificate-identity-regexp) and
+    --certificate-oidc-issuer (or --certificate-oidc-issuer-regexp).
+
+    Pass --insecure-ignore-tlog to verify a private keyless signature made
+    with --tlog-upload=false: it drops the requirement for a Rekor
+    transparency-log entry and relies on the timestamp-authority timestamp
+    instead. It has no effect on key-based verification.
+usage: sbx kit verify REFERENCE [flags]
+options:
+    - name: certificate-identity
+      usage: Exact keyless signer identity (certificate SAN)
+    - name: certificate-identity-regexp
+      usage: Keyless signer identity regexp (certificate SAN)
+    - name: certificate-oidc-issuer
+      usage: Exact keyless OIDC issuer
+    - name: certificate-oidc-issuer-regexp
+      usage: Keyless OIDC issuer regexp
+    - name: help
+      shorthand: h
+      default_value: "false"
+      usage: help for verify
+    - name: insecure-ignore-tlog
+      default_value: "false"
+      usage: |
+        Do not require a Rekor transparency-log entry (for private keyless signatures)
+    - name: key
+      usage: Public key for key-based verification (PEM)
+inherited_options:
+    - name: debug
+      shorthand: D
+      default_value: "false"
+      usage: Enable debug logging
+example: |4-
+      # Verify a key-based signature
+      sbx kit verify --key cosign.pub ghcr.io/org/my-kit:1.0
+
+      # Verify a keyless signature by identity
+      sbx kit verify \
+        --certificate-identity user@example.com \
+        --certificate-oidc-issuer https://accounts.google.com \
+        ./my-kit/
+see_also:
+    - sbx kit - (Experimental) Manage kit artifacts

data/sbx_cli/sbx_mcp.yaml

@@ -2,6 +2,7 @@ name: sbx mcp
 synopsis: Manage MCP servers
 description: |
     Register and manage MCP servers for use with sandbox sessions.
+usage: sbx mcp COMMAND
 options:
     - name: help
       shorthand: h
@@ -18,5 +19,5 @@ see_also:
     - sbx mcp auth - Authorize MCP servers
     - sbx mcp inspect - Show MCP server details
     - sbx mcp load - Load an already-registered MCP server into a running sandbox
-    - sbx mcp ls - List registered MCP servers
+    - sbx mcp ls - List MCP servers, grouped by the gateway that serves them
     - sbx mcp rm - Remove a registered MCP server

data/sbx_cli/sbx_mcp_add.yaml

@@ -54,7 +54,7 @@ description: |-
 
       Client secrets (confidential clients):
         There is no --client-secret flag. The secret for a confidential client
-        lives in the encrypted secret store in the global scope under the
+        lives in the secret store in the global scope under the
         service name "mcp:<server>.client_secret", and is read from there
         whenever the server is used:
 

data/sbx_cli/sbx_mcp_auth.yaml

@@ -9,7 +9,10 @@ description: |-
 
     Running 'sbx mcp auth <server>' authorizes or reauthorizes one server. If the
     stored credential is expired, sbx asks the control plane to refresh it first and
-    only falls back to interactive OAuth when refresh needs user consent.
+    only falls back to interactive OAuth when refresh needs user consent. A name
+    with no local registration is resolved from the Docker MCP catalog and
+    authorized under its catalog name, so no 'sbx mcp add' is required for catalog
+    servers.
 
     Use 'sbx mcp auth status' to inspect hosted credential status without starting
     OAuth, and 'sbx mcp auth rm' to remove hosted credentials without removing

data/sbx_cli/sbx_mcp_ls.yaml

@@ -1,5 +1,14 @@
 name: sbx mcp ls
-synopsis: List registered MCP servers
+synopsis: List MCP servers, grouped by the gateway that serves them
+description: |-
+    List registered MCP servers under the gateway that serves them.
+
+    The gateway header reports where it runs, who controls it, and whether you are
+    signed in; each server row reports its transport and whether it is usable now.
+    Servers needing authorization carry the 'sbx mcp auth' next step.
+
+    Auth status is read without starting an OAuth flow — from the local token store
+    in local data-plane mode, otherwise from the hosted control plane.
 usage: sbx mcp ls [flags]
 options:
     - name: help

data/sbx_cli/sbx_prune.yaml

@@ -0,0 +1,48 @@
+name: sbx prune
+synopsis: Remove all stopped sandboxes
+description: |-
+    Remove all stopped sandboxes and their associated resources.
+
+    Only stopped sandboxes are candidates — a running sandbox is never removed,
+    which makes this safe to run habitually. Stop a sandbox first with
+    "sbx stop" if you want it pruned. To remove a specific sandbox regardless of
+    state, use "sbx rm SANDBOX".
+
+    Use --filter since=DURATION to narrow the set to sandboxes that have been
+    stopped for longer than DURATION (e.g. since=168h to keep anything stopped
+    within the last week). A sandbox whose stop time the daemon cannot report is
+    left alone, since how long it has been stopped cannot be established.
+
+    Use --dry-run to list what would be removed without removing anything.
+
+    Pruning requires confirmation; use --force to skip the confirmation prompt
+    (for non-interactive scripts) and to remove a sandbox that is in use (e.g. an
+    open SSH connection). This action cannot be undone.
+
+    Local-only: cloud sandboxes expire via their TTL.
+usage: sbx prune [flags]
+options:
+    - name: dry-run
+      default_value: "false"
+      usage: |
+        List the sandboxes that would be removed without removing them
+    - name: filter
+      default_value: '[]'
+      usage: |
+        Filter candidates (supported: since=DURATION — stopped for longer than DURATION)
+    - name: force
+      shorthand: f
+      default_value: "false"
+      usage: |
+        Skip confirmation prompts and remove even if in use (e.g. an open SSH connection)
+    - name: help
+      shorthand: h
+      default_value: "false"
+      usage: help for prune
+inherited_options:
+    - name: debug
+      shorthand: D
+      default_value: "false"
+      usage: Enable debug logging
+see_also:
+    - sbx - Manage AI coding agent sandboxes.

data/sbx_cli/sbx_reset.yaml

@@ -9,6 +9,7 @@ description: |-
     - Clear all internal registries
     - Delete all sandbox state
     - Remove all policies
+    - Remove the managed SSH configuration
     - Clear the Gordon assistant's sessions and history
     - Delete all stored secrets
     - Sign out of Docker Sandboxes

data/sbx_cli/sbx_run.yaml

@@ -29,6 +29,15 @@ options:
       default_value: '[]'
       usage: |
         Add a per-sandbox network deny rule at creation time. Can be specified multiple times. The rule applies only to the new sandbox and can be listed or removed later with `sbx policy ls <NAME>` / `sbx policy rm network --sandbox <NAME> --resource <HOST>`. Safe under centralized governance because a local deny can only narrow, never widen, egress.
+    - name: env
+      shorthand: e
+      default_value: '[]'
+      usage: |
+        Set an environment variable in the sandbox (can be repeated): KEY=VALUE, or a bare KEY to take the value from the current environment. Applies to the agent session, so it takes effect on a re-attach too; also baked into the sandbox when this run creates it
+    - name: env-file
+      default_value: '[]'
+      usage: |
+        Read environment variables from a file (can be repeated). --env wins over any file; a later file wins over an earlier one. Applies to the agent session, so it takes effect on a re-attach too; also baked into the sandbox when this run creates it
     - name: help
       shorthand: h
       default_value: "false"

data/sbx_cli/sbx_secret.yaml

@@ -14,6 +14,7 @@ description: |-
       default. They are not injected into sandboxes unless --all-sandboxes or
       --sandbox is set (the credential never enters the sandbox filesystem).
       Use "sbx secret set --registry <host> --password-stdin" to store them.
+usage: sbx secret COMMAND
 options:
     - name: help
       shorthand: h

data/sbx_cli/sbx_secret_set-custom.yaml

@@ -18,6 +18,8 @@ description: |-
     specific sandbox.
 usage: sbx secret set-custom [flags]
 options:
+    - name: command
+      usage: Use a command's standard output as the secret value
     - name: env
       usage: Set this env var in the sandbox to the placeholder value
     - name: help
@@ -28,11 +30,24 @@ options:
       default_value: '[]'
       usage: |
         Host, IP, or wildcard pattern (e.g. *.example.com); repeatable
+    - name: no-verify
+      default_value: "false"
+      usage: Skip checking the --ref or --command source when storing it
     - name: placeholder
       usage: |
         Placeholder value; use {rand} for a random suffix (e.g. sk-{rand})
+    - name: ref
+      usage: |
+        Use a 1Password op:// reference or AWS Secrets Manager ARN as the secret source
+    - name: refresh
+      usage: |
+        Secret refresh policy: on-demand (default) or after a duration
     - name: sandbox
       usage: 'Scope the secret to one sandbox (default: all sandboxes)'
+    - name: show-error
+      default_value: "false"
+      usage: |
+        Show resolver standard error if the initial check fails (may contain secrets)
     - name: token
       shorthand: t
       usage: 'Secret value (less secure: visible in shell history)'

data/sbx_cli/sbx_secret_set.yaml

@@ -1,27 +1,44 @@
 name: sbx secret set
 synopsis: Create or update a secret
 description: |-
-    Create or update a secret for a service or registry.
+    Create or update a service secret or registry credential.
+
+    ### Service secrets
 
     Available services: anthropic, cursor, droid, github, google, groq, mistral, nebius, openai, openrouter, xai
 
     Service secrets apply globally by default. Use --sandbox to scope a secret to
     one sandbox. When SERVICE is omitted, an interactive prompt selects it.
 
-    Unlike service secrets, registry credentials are host-only by default. Use
-    --registry to store pull credentials for a container registry:
-      - Default: host-only. Used for template and kit pulls on the host;
-        never injected into a sandbox.
-      - With --all-sandboxes: used for host pulls and injected by the proxy into
-        every new sandbox's registry login. The credential itself never enters
-        the sandbox.
-      - With --sandbox: injected into that one sandbox only.
+    ### Dynamic secrets
+
+    Use --ref or --command to store a secret source instead of the secret value.
+    sbx resolves the source on the host when needed and caches the value according
+    to the --refresh policy.
+
+    --ref supports 1Password op:// references and AWS Secrets Manager ARNs. The
+    corresponding op or aws CLI must be installed and authenticated. --command
+    runs a shell command and uses its standard output as the secret value.
+
+    ### Registry credentials
+
+    Use --registry to store pull credentials for a container registry. Unlike
+    service secrets, registry credentials are host-only by default:
+
+    - By default, credentials are used for template and kit pulls on the host.
+      They are never injected into a sandbox.
+    - With --all-sandboxes, credentials are used for host pulls and injected by
+      the proxy into every new sandbox's registry login. The credentials never
+      enter the sandbox.
+    - With --sandbox, credentials are injected into the specified sandbox only.
 usage: sbx secret set [SERVICE] [flags]
 options:
     - name: all-sandboxes
       default_value: "false"
       usage: |
         Inject registry credentials into every sandbox (requires --registry)
+    - name: command
+      usage: Use a command's standard output as the secret value
     - name: force
       shorthand: f
       default_value: "false"
@@ -30,6 +47,9 @@ options:
       shorthand: h
       default_value: "false"
       usage: help for set
+    - name: no-verify
+      default_value: "false"
+      usage: Skip checking the --ref or --command source when storing it
     - name: oauth
       default_value: "false"
       usage: Start OAuth flow and store OAuth tokens (openai/global only)
@@ -37,10 +57,20 @@ options:
       default_value: "false"
       usage: |
         Read registry password or token from stdin (use with --registry)
+    - name: ref
+      usage: |
+        Use a 1Password op:// reference or AWS Secrets Manager ARN as the secret source
+    - name: refresh
+      usage: |
+        Secret refresh policy: on-demand or after a duration (default: 55m)
     - name: registry
       usage: Registry hostname for pull credentials (e.g. ghcr.io)
     - name: sandbox
       usage: Scope the secret to one sandbox instead of its default scope
+    - name: show-error
+      default_value: "false"
+      usage: |
+        Show resolver standard error if the initial check fails (may contain secrets)
     - name: token
       shorthand: t
       usage: 'Secret value (less secure: visible in shell history)'
@@ -65,6 +95,15 @@ example: |4-
       # Start OpenAI OAuth flow and store global OAuth tokens
       sbx secret set openai --oauth
 
+      # Resolve a 1Password reference at use time (requires an authenticated op CLI)
+      sbx secret set anthropic --ref 'op://Private/Anthropic/api-key'
+
+      # Resolve an AWS Secrets Manager ARN at use time (requires an authenticated aws CLI)
+      sbx secret set anthropic --ref 'arn:aws:secretsmanager:us-west-2:123456789012:secret:anthropic-api-key'
+
+      # Resolve a secret using an arbitrary command
+      sbx secret set github --command 'gh auth token'
+
       # Registry: host-only (template/kit pulls, not injected into sandboxes)
       gh auth token | sbx secret set --registry ghcr.io --password-stdin
 

data/sbx_cli/sbx_setup.yaml

@@ -8,7 +8,7 @@ description: |-
     Agent secrets are detected from the built-in agent kit specs and the
     env vars set on this host, and accepted secrets are imported into the global
     secrets store (the same store as "sbx secret set").
-usage: sbx setup
+usage: sbx setup [COMMAND]
 options:
     - name: help
       shorthand: h

data/sbx_cli/sbx_setup_ssh.yaml

@@ -2,8 +2,9 @@ name: sbx setup ssh
 synopsis: Set up SSH client config for the sandbox endpoint
 experimental: true
 description: |-
-    Write an ~/.ssh/config block + known_hosts so "ssh <name>.sbx" connects
-    to a sandbox with no prompts. Re-run any time; it's idempotent.
+    Write a generated SSH config + known_hosts and include it from
+    ~/.ssh/config so "ssh <name>.sbx" connects with no prompts. Named app instances
+    use "ssh <name>.sbx-<app>" instead. Re-run any time; it's idempotent.
 
     No SSH client key is needed — authentication is handled by the daemon's Unix
     socket (OS user boundary) combined with an active Docker login. Sign in first
@@ -27,3 +28,4 @@ example: |4-
       ssh my-sandbox.sbx -- echo hello
 see_also:
     - sbx setup - (Experimental) Detect host configuration and prepare Docker Sandboxes
+    - sbx setup ssh remove - Remove SSH client config for the current local app instance

data/sbx_cli/sbx_setup_ssh_remove.yaml

@@ -0,0 +1,16 @@
+name: sbx setup ssh remove
+synopsis: Remove SSH client config for the current local app instance
+experimental: true
+usage: sbx setup ssh remove [flags]
+options:
+    - name: help
+      shorthand: h
+      default_value: "false"
+      usage: help for remove
+inherited_options:
+    - name: debug
+      shorthand: D
+      default_value: "false"
+      usage: Enable debug logging
+see_also:
+    - sbx setup ssh - Set up SSH client config for the sandbox endpoint

data/sbx_cli/sbx_skills.yaml

@@ -9,6 +9,7 @@ description: |-
 
     Sandboxes with skills sharing enabled mount the store read-write. Use
     --no-share-skills when creating a sandbox to opt out.
+usage: sbx skills COMMAND
 options:
     - name: help
       shorthand: h
@@ -22,3 +23,4 @@ inherited_options:
 see_also:
     - sbx - Manage AI coding agent sandboxes.
     - sbx skills import - Import skills from supported agent directories
+    - sbx skills ls - List imported skills

data/sbx_cli/sbx_skills_ls.yaml

@@ -0,0 +1,18 @@
+name: sbx skills ls
+synopsis: List imported skills
+experimental: true
+description: |
+    List the skill folders in the central agent-skills store shared by sandboxes.
+usage: sbx skills ls [flags]
+options:
+    - name: help
+      shorthand: h
+      default_value: "false"
+      usage: help for ls
+inherited_options:
+    - name: debug
+      shorthand: D
+      default_value: "false"
+      usage: Enable debug logging
+see_also:
+    - sbx skills - (Experimental) Manage skills shared across sandboxes