docker-docs/data/sbx_cli/sbx_create_docker-agent.yaml

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

    The workspace path is 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; a read-only argument may name a single file, which holds
    that one path out of reach inside a workspace the sandbox can otherwise write.

    Omit the path to create a sandbox without a workspace bind mount: the agent
    then works in the container's own filesystem instead of on your files.

    Use "sbx run --name SANDBOX" to attach to the agent after creation.

    With --cloud:
    Create a cloud sandbox for docker-agent.

    Cloud sandboxes have no host workspace, so no path follows the agent. Sizing
    comes from --cpus and --memory and must land on a billable shape; without them
    a cloud sandbox gets 2 CPUs and 4 GiB. A template named with -t / --template
    must already exist in the cloud registry.

    Cloud sandboxes use cloud network policies. Host network and HTTP policies
    do not apply. Set cloud account defaults with
    "sbx --cloud policy init <allow-all|balanced|deny-all>".

    Use "sbx --cloud run --name SANDBOX" to attach to the agent after creation.
usage: sbx create docker-agent [PATH...] [flags]
options:
    - name: help
      shorthand: h
      default_value: "false"
      usage: help for docker-agent
inherited_options:
    - name: allow-network
      usage: |
        Network pattern to allow for cloud sandbox egress (cloud only; can be specified multiple times)
    - 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: 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: 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
      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>' or '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: image-ref
      usage: |
        OCI image reference for inline-mode cloud create (mutually exclusive with --template; requires --cpus and --memory)
    - name: kit
      default_value: '[]'
      experimental: true
      usage: |
        Additional kit reference (must be a mixin; directory, ZIP, git, or OCI). Can be specified multiple times
    - name: kit-arg
      default_value: '[]'
      experimental: true
      usage: |
        Value for an argument the kit declares, as name=value for every kit or kit.name=value for one (can be repeated)
    - name: kit-args-file
      default_value: '[]'
      experimental: true
      usage: |
        File of name=value kit arguments, one per line (can be repeated); --kit-arg overrides
    - name: memory
      shorthand: m
      usage: |
        Memory limit in binary units (e.g., 512m, 8g). Minimum: 512 MiB. Default: 50% of host memory, clamped to 512 MiB–32 GiB. Maximum: max(75% of host memory, 512 MiB)
    - 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 (periods are rejected with --cloud); 'default' is reserved)
    - name: on-timeout
      usage: |
        What happens when --ttl lapses: 'stop' stops the sandbox in place so it can be started again later, 'restart' keeps it running by stopping and immediately starting it, or 'delete' removes it. Omit the flag and the server stops the sandbox when it can be started again later, and deletes it otherwise. With 'restart' a supplied --ttl must be at least 1h (cloud only).
    - 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: pull
      default_value: always
      usage: Image pull policy (always|missing|never)
    - name: quiet
      shorthand: q
      default_value: "false"
      usage: Suppress verbose output
    - name: skills
      usage: |
        Shared skills store mode for the agent's skills directory (e.g. ~/.claude/skills): off, readonly (store linked in read-only, directory stays writable), or readwrite (store mounted over it, writes are shared). Default: readonly, or the configured skills.defaultMode setting.
    - name: static-mcp
      default_value: '[]'
      usage: |
        MCP server names that form the sandbox's fixed (static) MCP set. Accepts a comma-separated list (--static-mcp notion,atlassian), repeated flags (--static-mcp notion --static-mcp atlassian), or a mix; all forms accumulate into the same set. The set is chosen once at creation time. Local sandboxes take names registered with 'sbx mcp add'. Cloud sandboxes resolve names on the cloud MCP gateway.
    - name: template
      shorthand: t
      usage: |
        Container image to use for the sandbox (default: agent-specific image)
    - name: ttl
      usage: |
        Cloud sandbox time-to-live before it times out (e.g. 30m, 2h, 1h30m; units are case-insensitive; cloud only; default: server-side)
    - name: volume
      shorthand: v
      default_value: '[]'
      experimental: true
      usage: |
        Attach an existing persistent volume, NAME:MOUNTPATH (cloud only, experimental; repeatable)
example: |4-
      # Create in the current directory
      sbx create docker-agent .

      # Create with a specific path
      sbx create docker-agent /path/to/project

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

      # Create without a workspace bind mount
      sbx create docker-agent

      # Create a cloud sandbox for docker-agent
      sbx --cloud create docker-agent

      # Create a named cloud sandbox with a mixin baked in
      sbx --cloud create --name my-project docker-agent --kit ./my-mixin/

      # Create from a template that already exists in the cloud registry
      sbx --cloud create -t TEMPLATE
see_also:
    - sbx create - Create a sandbox for an agent