name: sbx env
synopsis: |
    Manage sandboxes declaratively from an sbxenv.yaml file
experimental: true
description: |-
    Manage a sandbox declared in an sbxenv.yaml file. The file selects the agent,
    kits, workspace mounts, environment variables, secrets, and credential bindings.

    Use create to provision the sandbox, run to start or join its agent session,
    exec to run a command, and rm to remove it and its provisioned secrets.
    Use plan to preview changes. Changes require approval; --force skips the prompt.

    Lifecycle commands, command-based secrets, and command-backed MCP servers execute
    on the host with your permissions. Keep secret helpers and their dependencies
    outside writable sandbox mounts, and use absolute helper paths.

    MCP command approval persists across sandbox and daemon restarts. Use
    --skip-host-commands to skip lifecycle commands and disable owned host MCP
    commands until a later "sbx env run" without the flag. If initialize creates
    a missing MCP executable or changes its resolved path, a second approval is
    required before registration or sandbox creation.

    The environment file is mounted read-only by default when shared with the
    sandbox. Set sandboxOptions.writableEnvFiles only when you trust the agent
    to change what future invocations run on the host.

    With --cloud, manage a cloud sandbox from the same file. Host workspace mounts,
    host port bindings, MCP definitions, registry credentials, and unsnapshotted
    dynamic secret sources are unsupported. Clone the project inside the sandbox instead.

    Secrets and bindings are provisioned at creation; changes require recreating
    the sandbox. Removal deletes secrets provisioned by this environment; bindings
    are retained unless --prune-bindings is passed. Use the same cloud target,
    identity, and ordered files for subsequent commands.

    For file syntax and workflows, see:
    https://docs.docker.com/ai/sandboxes/configuration/environment-files/
usage: sbx env COMMAND
options:
    - name: help
      shorthand: h
      default_value: "false"
      usage: help for env
inherited_options:
    - name: cloud
      default_value: "false"
      usage: |
        Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list)
    - name: debug
      shorthand: D
      default_value: "false"
      usage: Enable debug logging
    - name: no-input
      default_value: "false"
      usage: |
        Never prompt; commands that need an answer fail with the command to run instead
see_also:
    - sbx - Manage AI coding agent sandboxes.
    - sbx env create - Create a sandbox environment from sbxenv.yaml
    - sbx env exec - Execute a command inside a sandbox environment
    - sbx env plan - Show what an environment would change outside the sandbox
    - sbx env rm - Remove a sandbox environment and its scoped resources
    - sbx env run - Create (if needed) and attach to a sandbox environment