docs/data/sbx_cli/sbx_create.yaml

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

    Use "sbx run --name SANDBOX" to attach to the agent after creation.
usage: sbx create [flags] AGENT PATH [PATH...]
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: 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: help
      shorthand: h
      default_value: "false"
      usage: help for create
    - 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)
inherited_options:
    - name: debug
      shorthand: D
      default_value: "false"
      usage: Enable debug logging
example: |4-
      # Create a sandbox for Claude in the current directory
      sbx create claude .

      # Create a sandbox with a custom name
      sbx create --name my-project claude /path/to/project

      # Create with additional read-only workspaces
      sbx create claude . /path/to/docs:ro

      # Run the agent on an in-container clone of the host repo, wired back via a git-daemon
      sbx create --clone claude .
see_also:
    - sbx - Manage AI coding agent sandboxes.
    - sbx create claude - Create a sandbox for claude
    - sbx create codex - Create a sandbox for codex
    - sbx create copilot - Create a sandbox for copilot
    - sbx create cursor - Create a sandbox for cursor
    - sbx create docker-agent - Create a sandbox for docker-agent
    - sbx create droid - Create a sandbox for droid
    - sbx create gemini - Create a sandbox for gemini
    - sbx create kiro - Create a sandbox for kiro
    - sbx create opencode - Create a sandbox for opencode
    - sbx create shell - Create a sandbox for shell