name: sbx create shell
synopsis: Create a sandbox for shell
description: |-
    Create a sandbox with access to a host workspace for shell.

    The workspace path is required and will be mounted inside the sandbox at the
    same path as on the host. Additional workspaces can be provided as extra
    arguments. Append ":ro" to mount them read-only.

    Use "sbx run --name SANDBOX" to attach to the agent after creation.
usage: sbx create shell PATH [PATH...] [flags]
options:
    - name: help
      shorthand: h
      default_value: "false"
      usage: help for shell
inherited_options:
    - name: clone
      default_value: "false"
      usage: |
        Run the agent on a private in-container clone of the host Git repository (mounted read-only) instead of bind-mounting the workspace; the agent's commits are accessible via the sandbox-<name> git remote on the host
    - name: cpus
      default_value: "0"
      usage: |
        Number of CPUs to allocate to the sandbox (0 = auto: all host CPUs)
    - name: debug
      shorthand: D
      default_value: "false"
      usage: Enable debug logging
    - name: deny-network
      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
      usage: |
        Kit reference (directory, ZIP, or OCI). Can be specified multiple times
    - name: memory
      shorthand: m
      usage: |
        Memory limit in binary units (e.g., 1024m, 8g). Default: 50% of host memory, max 32 GiB
    - name: name
      usage: |
        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: '[]'
      usage: |
        Publish a sandbox port to the host (can be repeated): [[HOST_IP:]HOST_PORT:]SANDBOX_PORT[/PROTOCOL]
    - name: quiet
      shorthand: q
      default_value: "false"
      usage: Suppress verbose output
    - name: template
      shorthand: t
      usage: |
        Container image to use for the sandbox (default: agent-specific image)
example: |4-
      # Create in the current directory
      sbx create shell .

      # Create with a specific path
      sbx create shell /path/to/project

      # Create with additional read-only workspaces
      sbx create shell . /path/to/docs:ro
see_also:
    - sbx create - Create a sandbox for an agent