diff --git a/data/sbx_cli/sbx.yaml b/data/sbx_cli/sbx.yaml index bffd7ef2ef..239291883d 100644 --- a/data/sbx_cli/sbx.yaml +++ b/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 diff --git a/data/sbx_cli/sbx_completion.yaml b/data/sbx_cli/sbx_completion.yaml index 1416516a62..ecab3f1117 100644 --- a/data/sbx_cli/sbx_completion.yaml +++ b/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 diff --git a/data/sbx_cli/sbx_create.yaml b/data/sbx_cli/sbx_create.yaml index 981108256c..394b540713 100644 --- a/data/sbx_cli/sbx_create.yaml +++ b/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 ` / `sbx policy rm network --sandbox --resource `. 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: -, letters, numbers, hyphens, periods, plus signs and minus signs only) + Name for the sandbox (defaults to -; 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: '[]' diff --git a/data/sbx_cli/sbx_create_claude.yaml b/data/sbx_cli/sbx_create_claude.yaml index 33123b7a14..9f3fd598ea 100644 --- a/data/sbx_cli/sbx_create_claude.yaml +++ b/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 ` / `sbx policy rm network --sandbox --resource `. 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: -, letters, numbers, hyphens, periods, plus signs and minus signs only) + Name for the sandbox (defaults to -; 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: '[]' diff --git a/data/sbx_cli/sbx_create_codex.yaml b/data/sbx_cli/sbx_create_codex.yaml index d6fa02e323..f1d3bece13 100644 --- a/data/sbx_cli/sbx_create_codex.yaml +++ b/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 ` / `sbx policy rm network --sandbox --resource `. 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: -, letters, numbers, hyphens, periods, plus signs and minus signs only) + Name for the sandbox (defaults to -; 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: '[]' diff --git a/data/sbx_cli/sbx_create_copilot.yaml b/data/sbx_cli/sbx_create_copilot.yaml index 21fb6f94ca..29d8a9d559 100644 --- a/data/sbx_cli/sbx_create_copilot.yaml +++ b/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 ` / `sbx policy rm network --sandbox --resource `. 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: -, letters, numbers, hyphens, periods, plus signs and minus signs only) + Name for the sandbox (defaults to -; 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: '[]' diff --git a/data/sbx_cli/sbx_create_cursor.yaml b/data/sbx_cli/sbx_create_cursor.yaml index e5c1cc91d4..fb7564c1ff 100644 --- a/data/sbx_cli/sbx_create_cursor.yaml +++ b/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 ` / `sbx policy rm network --sandbox --resource `. 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: -, letters, numbers, hyphens, periods, plus signs and minus signs only) + Name for the sandbox (defaults to -; 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: '[]' diff --git a/data/sbx_cli/sbx_create_docker-agent.yaml b/data/sbx_cli/sbx_create_docker-agent.yaml index 1421def0a0..2dc8938a2d 100644 --- a/data/sbx_cli/sbx_create_docker-agent.yaml +++ b/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 ` / `sbx policy rm network --sandbox --resource `. 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: -, letters, numbers, hyphens, periods, plus signs and minus signs only) + Name for the sandbox (defaults to -; 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: '[]' diff --git a/data/sbx_cli/sbx_create_droid.yaml b/data/sbx_cli/sbx_create_droid.yaml index a6da121023..168e70ccff 100644 --- a/data/sbx_cli/sbx_create_droid.yaml +++ b/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 ` / `sbx policy rm network --sandbox --resource `. 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: -, letters, numbers, hyphens, periods, plus signs and minus signs only) + Name for the sandbox (defaults to -; 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: '[]' diff --git a/data/sbx_cli/sbx_create_gemini.yaml b/data/sbx_cli/sbx_create_gemini.yaml index 2fc2765b0a..cc3fd91658 100644 --- a/data/sbx_cli/sbx_create_gemini.yaml +++ b/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 ` / `sbx policy rm network --sandbox --resource `. 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: -, letters, numbers, hyphens, periods, plus signs and minus signs only) + Name for the sandbox (defaults to -; 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: '[]' diff --git a/data/sbx_cli/sbx_create_kiro.yaml b/data/sbx_cli/sbx_create_kiro.yaml index 3f7180c193..2008da0763 100644 --- a/data/sbx_cli/sbx_create_kiro.yaml +++ b/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 ` / `sbx policy rm network --sandbox --resource `. 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: -, letters, numbers, hyphens, periods, plus signs and minus signs only) + Name for the sandbox (defaults to -; 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: '[]' diff --git a/data/sbx_cli/sbx_create_opencode.yaml b/data/sbx_cli/sbx_create_opencode.yaml index 0a383c92cb..298a78de30 100644 --- a/data/sbx_cli/sbx_create_opencode.yaml +++ b/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 ` / `sbx policy rm network --sandbox --resource `. 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: -, letters, numbers, hyphens, periods, plus signs and minus signs only) + Name for the sandbox (defaults to -; 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: '[]' diff --git a/data/sbx_cli/sbx_create_shell.yaml b/data/sbx_cli/sbx_create_shell.yaml index 29dff3922d..1d56a43094 100644 --- a/data/sbx_cli/sbx_create_shell.yaml +++ b/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 ` / `sbx policy rm network --sandbox --resource `. 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: -, letters, numbers, hyphens, periods, plus signs and minus signs only) + Name for the sandbox (defaults to -; 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: '[]' diff --git a/data/sbx_cli/sbx_daemon.yaml b/data/sbx_cli/sbx_daemon.yaml index c8959a703f..f7a913bd46 100644 --- a/data/sbx_cli/sbx_daemon.yaml +++ b/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 diff --git a/data/sbx_cli/sbx_daemon_log-level.yaml b/data/sbx_cli/sbx_daemon_log-level.yaml index cf4127595e..20822ef1bd 100644 --- a/data/sbx_cli/sbx_daemon_log-level.yaml +++ b/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 diff --git a/data/sbx_cli/sbx_kit.yaml b/data/sbx_cli/sbx_kit.yaml index afe0d179dc..1fd4787057 100644 --- a/data/sbx_cli/sbx_kit.yaml +++ b/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 diff --git a/data/sbx_cli/sbx_kit_provenance.yaml b/data/sbx_cli/sbx_kit_provenance.yaml new file mode 100644 index 0000000000..07a876d494 --- /dev/null +++ b/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 diff --git a/data/sbx_cli/sbx_kit_push.yaml b/data/sbx_cli/sbx_kit_push.yaml index 3de9a8565a..9b4a6ac355 100644 --- a/data/sbx_cli/sbx_kit_push.yaml +++ b/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 diff --git a/data/sbx_cli/sbx_kit_sign.yaml b/data/sbx_cli/sbx_kit_sign.yaml new file mode 100644 index 0000000000..7319af55f3 --- /dev/null +++ b/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 diff --git a/data/sbx_cli/sbx_kit_verify.yaml b/data/sbx_cli/sbx_kit_verify.yaml new file mode 100644 index 0000000000..8c5552fb36 --- /dev/null +++ b/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 diff --git a/data/sbx_cli/sbx_mcp.yaml b/data/sbx_cli/sbx_mcp.yaml index dbeaf7878f..9136744af8 100644 --- a/data/sbx_cli/sbx_mcp.yaml +++ b/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 diff --git a/data/sbx_cli/sbx_mcp_add.yaml b/data/sbx_cli/sbx_mcp_add.yaml index d6778577d7..579f5a3dff 100644 --- a/data/sbx_cli/sbx_mcp_add.yaml +++ b/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:.client_secret", and is read from there whenever the server is used: diff --git a/data/sbx_cli/sbx_mcp_auth.yaml b/data/sbx_cli/sbx_mcp_auth.yaml index 957e588bca..1271b8c91b 100644 --- a/data/sbx_cli/sbx_mcp_auth.yaml +++ b/data/sbx_cli/sbx_mcp_auth.yaml @@ -9,7 +9,10 @@ description: |- Running 'sbx mcp auth ' 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 diff --git a/data/sbx_cli/sbx_mcp_ls.yaml b/data/sbx_cli/sbx_mcp_ls.yaml index 4ed1a21c10..323182f953 100644 --- a/data/sbx_cli/sbx_mcp_ls.yaml +++ b/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 diff --git a/data/sbx_cli/sbx_prune.yaml b/data/sbx_cli/sbx_prune.yaml new file mode 100644 index 0000000000..45576ed6db --- /dev/null +++ b/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. diff --git a/data/sbx_cli/sbx_reset.yaml b/data/sbx_cli/sbx_reset.yaml index 3eede2799d..66eae81408 100644 --- a/data/sbx_cli/sbx_reset.yaml +++ b/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 diff --git a/data/sbx_cli/sbx_run.yaml b/data/sbx_cli/sbx_run.yaml index cf0083b8bf..e80550ad97 100644 --- a/data/sbx_cli/sbx_run.yaml +++ b/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 ` / `sbx policy rm network --sandbox --resource `. 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" diff --git a/data/sbx_cli/sbx_secret.yaml b/data/sbx_cli/sbx_secret.yaml index f645edd996..995fb11934 100644 --- a/data/sbx_cli/sbx_secret.yaml +++ b/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 --password-stdin" to store them. +usage: sbx secret COMMAND options: - name: help shorthand: h diff --git a/data/sbx_cli/sbx_secret_set-custom.yaml b/data/sbx_cli/sbx_secret_set-custom.yaml index 30b7745909..3668ca5380 100644 --- a/data/sbx_cli/sbx_secret_set-custom.yaml +++ b/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)' diff --git a/data/sbx_cli/sbx_secret_set.yaml b/data/sbx_cli/sbx_secret_set.yaml index 0b1bd332a9..cdad8cfabb 100644 --- a/data/sbx_cli/sbx_secret_set.yaml +++ b/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 diff --git a/data/sbx_cli/sbx_setup.yaml b/data/sbx_cli/sbx_setup.yaml index cd8e4e7f8f..d7175ca0a2 100644 --- a/data/sbx_cli/sbx_setup.yaml +++ b/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 diff --git a/data/sbx_cli/sbx_setup_ssh.yaml b/data/sbx_cli/sbx_setup_ssh.yaml index 8d24c6db9e..0e37c56bd5 100644 --- a/data/sbx_cli/sbx_setup_ssh.yaml +++ b/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 .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 .sbx" connects with no prompts. Named app instances + use "ssh .sbx-" 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 diff --git a/data/sbx_cli/sbx_setup_ssh_remove.yaml b/data/sbx_cli/sbx_setup_ssh_remove.yaml new file mode 100644 index 0000000000..6633cc7804 --- /dev/null +++ b/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 diff --git a/data/sbx_cli/sbx_skills.yaml b/data/sbx_cli/sbx_skills.yaml index 9831ff7b26..5a56085f16 100644 --- a/data/sbx_cli/sbx_skills.yaml +++ b/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 diff --git a/data/sbx_cli/sbx_skills_ls.yaml b/data/sbx_cli/sbx_skills_ls.yaml new file mode 100644 index 0000000000..a8c3c92ce9 --- /dev/null +++ b/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