Management CLI reference

List every local Docker image reference, including untagged image IDs that can create a sandbox.

When to use it

1. Call this before create_sandbox when the caller needs a valid local image reference.
2. The result may contain tags, digests, and untagged image IDs. Pass the selected string unchanged.
3. This operation does not pull an image or create a sandbox.

Syntax

sandbox-manager-cli list_docker_images

Arguments

No arguments.

Examples

sandbox-manager-cli list_docker_images

Representative result

{
  "images": [
    "ubuntu:24.04",
    "sha256:abc123…"
  ]
}

Result contract: images is the complete set returned by the configured runtime provider.

List picker-visible workspace roots when path is omitted, or up to 500 immediate local subdirectories of a selected workspace directory.

When to use it

1. Omit path to list picker-visible roots, then browse one returned absolute path at a time.
2. Only immediate subdirectories are returned; repeat the call to walk deeper.
3. Use the selected absolute path as create_sandbox.workspace_root.

Syntax

sandbox-manager-cli list_workspace_directories [--path PATH]

Arguments

Examples

sandbox-manager-cli list_workspace_directories
sandbox-manager-cli list_workspace_directories --path /home/me/project

Representative result

{
  "path": "/host/workspaces",
  "parent": "/host",
  "truncated": false,
  "directories": [
    {
      "name": "example",
      "path": "/host/workspaces/example"
    }
  ]
}

Result contract: path and parent may be null at a configured root. truncated becomes true after the browse limit.

Create a host-side sandbox record, create the runtime sandbox, and start its daemon.

When to use it

1. Choose an image and workspace root with the two host-discovery operations first.
2. The manager creates or reuses a shared read-only base, installs daemon assets, waits for readiness, and records endpoints.
3. A failed multi-create batch is rolled back. Successful creation changes host and container state.

Syntax

sandbox-manager-cli create_sandbox --image IMAGE --workspace-bind-root PATH [--count N]

Arguments

Examples

sandbox-manager-cli create_sandbox --image ubuntu:24.04 --workspace-bind-root /testbed
sandbox-manager-cli create_sandbox --image ubuntu:24.04 --workspace-bind-root /testbed --count 5

Representative result

{
  "id": "sbox-example",
  "workspace_root": "/host/workspaces/example",
  "state": "ready",
  "daemon": {
    "host": "127.0.0.1",
    "port": 41001
  },
  "daemon_http": {
    "host": "127.0.0.1",
    "port": 42001
  },
  "shared_base": {
    "source": "/host/cache/shared-base/rootfs",
    "target": "/eos/layer-stack/shared-base",
    "root_hash": "sha256:…",
    "readonly": true
  }
}

Result contract: count 1 returns one record; count greater than 1 returns { sandboxes: [record, …] }.

List sandbox records known to the manager, including lifecycle state and configured daemon endpoint metadata.

When to use it

1. Use this as the primary read-only source of sandbox_id values and lifecycle state.
2. A record may lack usable daemon metadata while it is creating, stopping, stopped, or failed.
3. A stored endpoint does not prove reachability; use observability snapshot when health matters.

Syntax

sandbox-manager-cli list_sandboxes

Arguments

No arguments.

Examples

sandbox-manager-cli list_sandboxes

Representative result

{
  "sandboxes": [
    {
      "id": "sbox-example",
      "workspace_root": "/host/workspaces/example",
      "state": "ready",
      "daemon": {
        "host": "127.0.0.1",
        "port": 41001
      },
      "daemon_http": {
        "host": "127.0.0.1",
        "port": 42001
      },
      "shared_base": {
        "source": "/host/cache/shared-base/rootfs",
        "target": "/eos/layer-stack/shared-base",
        "root_hash": "sha256:…",
        "readonly": true
      }
    }
  ]
}

Result contract: sandboxes is empty when the manager has no records.

Inspect one sandbox record, including lifecycle state, workspace root, and configured daemon endpoint metadata.

When to use it

1. Call with an id from list_sandboxes when one record and its endpoint metadata are needed.
2. This reads the manager registry; it does not call the daemon or prove runtime health.
3. Treat workspace paths and endpoints as operational metadata.

Syntax

sandbox-manager-cli inspect_sandbox --sandbox-id ID

Arguments

Examples

sandbox-manager-cli inspect_sandbox --sandbox-id sbox-1

Representative result

{
  "id": "sbox-example",
  "workspace_root": "/host/workspaces/example",
  "state": "ready",
  "daemon": {
    "host": "127.0.0.1",
    "port": 41001
  },
  "daemon_http": {
    "host": "127.0.0.1",
    "port": 42001
  },
  "shared_base": {
    "source": "/host/cache/shared-base/rootfs",
    "target": "/eos/layer-stack/shared-base",
    "root_hash": "sha256:…",
    "readonly": true
  }
}

Result contract: daemon, daemon_http, and shared_base can be null outside the ready lifecycle state.

Stop the sandbox daemon, destroy the runtime sandbox, and remove the host-side sandbox record.

When to use it

1. Confirm the target with inspect_sandbox before calling.
2. The manager stops the daemon, destroys the runtime, marks the record stopped, and removes it.
3. If runtime destruction fails, the record is retained in failed state for operator recovery.

Syntax

sandbox-manager-cli destroy_sandbox --sandbox-id ID

Arguments

Examples

sandbox-manager-cli destroy_sandbox --sandbox-id sbox-1

Representative result

{
  "id": "sbox-example",
  "workspace_root": "/host/workspaces/example",
  "state": "stopped",
  "daemon": {
    "host": "127.0.0.1",
    "port": 41001
  },
  "daemon_http": {
    "host": "127.0.0.1",
    "port": 42001
  },
  "shared_base": {
    "source": "/host/cache/shared-base/rootfs",
    "target": "/eos/layer-stack/shared-base",
    "root_hash": "sha256:…",
    "readonly": true
  }
}

Result contract: Success returns the removed record in its final stopped state.

Squash every squashable block into equivalent flattened layers and migrate live workspace sessions onto the compact chains.

When to use it

1. Use this for operator-directed storage compaction; it changes the active layer manifest.
2. The daemon commits equivalent flattened layers and reports migration or lease dispositions.
3. A stale daemon without squash support returns operation_failed and must be recreated.

Syntax

sandbox-manager-cli squash_layerstacks --sandbox-id ID

Arguments

Examples

sandbox-manager-cli squash_layerstacks --sandbox-id sbox-1

Representative result

{
  "manifest_version": 5,
  "squashed_blocks": [
    {
      "squashed_layer_id": "layer-flat-5",
      "replaced_layer_ids": [
        "layer-2",
        "layer-3"
      ],
      "replaced_layers": "reclaimed"
    }
  ],
  "swept_sessions": [
    {
      "session_id": "workspace_17",
      "disposition": "migrated"
    }
  ]
}

Result contract: Optional blocked_reasons and faulty_sessions explain incomplete reclamation.

Fold every published layer above the base into a validated delta and apply it to a host directory or write an archive.

When to use it

1. Use dir to apply the delta to a host directory, or tar/tar-zst to atomically write an archive.
2. dest must be absolute. The filesystem root, home, manager state, and export spool paths are denied.
3. The manager validates daemon bytes and is the only component that writes the host destination.

Syntax

sandbox-manager-cli export_changes --sandbox-id ID --dest PATH [--format dir|tar|tar-zst]

Arguments

Examples

sandbox-manager-cli export_changes --sandbox-id sbox-1 --dest /home/me/myproject
sandbox-manager-cli export_changes --sandbox-id sbox-1 --dest /tmp/delta.tar.zst --format tar-zst

Representative result

{
  "manifest_version": 7,
  "format": "tar-zst",
  "layers_exported": [
    "layer-6",
    "layer-7"
  ],
  "files_written": 12,
  "symlinks_written": 1,
  "whiteouts_emitted": 2,
  "bytes_written": 48211
}

Result contract: dir results report deletes and opaque clears; archive results report emitted whiteouts.