> ## Documentation Index > Fetch the complete documentation index at: https://docs.tokenfactory.nebius.com/llms.txt > Use this file to discover all available pages before exploring further. # images - List and import images List images in the project. Images are the filesystem snapshots that sandboxes run from – every non-disposable `contree run` produces a new one. ## Examples ```bash theme={null} # List all images contree images # Filter by tag prefix contree images --prefix=ubuntu # Only tagged images contree images --tagged # Images created in the last hour contree images --since=1h # Find a specific image by UUID prefix contree images --uuid=3f2a7b # JSON output for scripting contree -f json images --tagged | jq -r '.tag' ``` ## Help output
\$ contree images --help
usage: contree images \[-h] \[--prefix PREFIX] \[-i UUID] \[-a] \[--since SINCE] \[--until UNTIL]
                      \[--limit LIMIT]
                      \{list,ls,import} ...

List and import sandbox images.

Without a subcommand, lists images (same as \`\`images list\`\`).

Subcommands:
  list (ls)     List images with filtering and pagination
  import        Import image from a container registry

positional arguments:
  \{list,ls,import}
    list (ls)       List images
    import          Import image from container registry

options:
  -h, --help        show this help message and exit
  --prefix PREFIX   Filter by tag prefix
  -i, --uuid UUID   Filter by image UUID
  -a, --all         Include untagged images (default: tagged only)
  --since SINCE     Parse +/- intervals (bare seconds or smhdMy) or ISO/date to UTC datetime.
  --until UNTIL     Show images before. Parse +/- intervals (bare seconds or smhdMy) or ISO/date
                    to UTC datetime.
  --limit LIMIT     Stop after this many images and warn if more are available (default: 3000)

examples:
  contree images --prefix=ubuntu
  contree images list --all
  contree images import ubuntu:latest
  contree images import ubuntu:\{latest,noble,jammy}
  contree images import ghcr.io/owner/image:tag

for coding agents:
  \`images\` / \`images list\` is read-only
  \`images import\` spawns async import operations and polls until completion
  supports brace expansion for batch imports
  Ctrl+C cancels all active import operations

agent note:
  Before using this command in an automated workflow, read:
    contree agent
## Filtering `--prefix` matches the beginning of the tag string. This is useful for browsing available base images: ```bash theme={null} contree images --prefix=python contree images --prefix=common/ ``` `--since` and `--until` accept either ISO timestamps or duration intervals like `1h`, `30m`, `7d`. ## Subcommands ### `images list` `contree images list` (alias `ls`) is the explicit form of the bare `contree images` invocation. Both share the same flag set – pick the explicit form when you want a command that reads symmetrically with `images import`, or in scripts that already use the subcommand style everywhere.
\$ contree images list --help
usage: contree images list \[-h] \[--prefix PREFIX] \[-i UUID] \[-a] \[--since SINCE] \[--until UNTIL]
                           \[--limit LIMIT]

options:
  -h, --help       show this help message and exit
  --prefix PREFIX  Filter by tag prefix
  -i, --uuid UUID  Filter by image UUID
  -a, --all        Include untagged images (default: tagged only)
  --since SINCE    Parse +/- intervals (bare seconds or smhdMy) or ISO/date to UTC datetime.
  --until UNTIL    Show images before. Parse +/- intervals (bare seconds or smhdMy) or ISO/date to
                   UTC datetime.
  --limit LIMIT    Stop after this many images and warn if more are available (default: 3000)
### `images import` `contree images import REF [REF ...]` pulls one or more images from an external OCI registry into the project and waits for the import operation to finish. Each reference may be a `docker://` URL or any form the platform accepts; multiple refs are imported sequentially with shared credentials, and Ctrl-C cancels the in-flight operation cleanly.
\$ contree images import --help
usage: contree images import \[-h] \[--username USERNAME] \[--password PASSWORD] \[-t TIMEOUT]
                             refs \[refs ...]

positional arguments:
  refs                  Image references (supports brace expansion)

options:
  -h, --help            show this help message and exit
  --username USERNAME   Registry username (enables credentials)
  --password PASSWORD   Registry password (prompted securely if --username given)
  -t, --timeout TIMEOUT
                        Import timeout in seconds

examples:
  contree images import ubuntu:latest
  contree images import --timeout 600 ubuntu:latest
  contree images import docker.io/ubuntu:latest
  contree images import docker://docker.io/ubuntu:latest
  contree images import ghcr.io/ubuntu/ubuntu:latest
  contree images import ubuntu:\{latest,noble,jammy}

for coding agents:
  mutating command — creates import operations
  all formats are normalised to docker://registry/path:tag
  polls every 5 seconds until all operations complete
  Ctrl+C cancels all active import operations
## See also * [tag - Tag or untag an image](./tag) – assign a tag to an image * [Your First Sandbox](../tutorial/first-steps) – browsing and choosing images