> ## 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.

# Inspect images without starting a VM

> Read, search, and download files directly from a saved filesystem.

The Inspect API gives access to files in an existing image or saved checkpoint without starting a VM or executing a command. Retrieve an artifact after execution has ended, examine configuration before a run, or search a saved result while keeping its filesystem unchanged.

An **image** is an immutable stored filesystem. A **checkpoint** is an image used as a continuation point. Inspection reads that saved state; it does not require the processes that produced it to keep running.

## Read a saved image

Complete [Set up access](https://docs.tokenfactory.nebius.com/sandboxes/start/set-up-access.md) and install the SDK as described in the [Python quickstart](https://docs.tokenfactory.nebius.com/sandboxes/start/python-quickstart.md). This complete example uses the existing `alpine:latest` tag. To inspect a saved result, replace the tag with its image UUID and choose a path in that image.

```python theme={null}
from contree_sdk import ContreeSession, create_sandbox_session

with create_sandbox_session(
    image="tag:alpine:latest", session_type=ContreeSession
) as session:
    image = session.inspect()
    print(image.read_file("/etc/os-release").decode())
    image.download_file("/etc/os-release", "os-release.txt")
```

`ContreeSession.inspect()` returns an inspector pinned to the selected image UUID. Opening this session and reading its files starts no VM. The program prints the operating system information and saves the same file locally as `os-release.txt`. Keep the inspector inside the session context so its connection remains open.

Paths refer to the image's filesystem root, independently of a command's working directory. The tag resolves to an image when the session opens; record `image.image_uuid` when the same state must be inspected again after a tag moves.

## What inspection can do

| Method | Use |
| - | - |
| `image.list("/etc")` | List directory entries and file metadata. |
| `image.read_file("/etc/os-release")` | Read a complete file as bytes. |
| `image.download_file("/etc/os-release", "os-release.txt")` | Download a file to a local path. |
| `image.grep("^NAME=", path="/etc/os-release")` | Search file contents and return structured matches. Check `truncated` when completeness matters. |
| `image.iter_file(path)` | Stream a large file in chunks. |
| `image.archive(path)` | Stream a file or directory as a tar archive. |

Close a stream if iteration stops early. Download destinations are local paths; their parent directories must exist. `download_file()` replaces its destination only after the full transfer succeeds.

## Saved images and live sessions

A saved-image inspector keeps the same immutable image UUID across later commands. Files that have not been saved into that image are outside its view, including staged attachments that execution has not yet applied.

The default SDK session is a `LazySession`, which can retain a running VM between commands. Its `inspect()` view selects a source for each request:

* With a running VM, it reads the live filesystem without stopping the VM. Concurrent writes can change what a request sees.
* With no running VM and no pending staged files, it reads the saved image without starting a VM.
* With pending staged files, a file request can start a VM to apply and include them.

Use `LazySession.inspect_snapshot()` for a stable saved-image view. On a running session, it waits for accepted work, saves the filesystem, and stops the VM. On a session with no running VM, it pins the existing image without starting a VM. Saving active changes and inspecting an already saved image are separate steps; inspection alone does not execute the workload that creates a result.

See [Images, checkpoints, and branches](https://docs.tokenfactory.nebius.com/sandboxes/concepts/images-checkpoints-and-branches.md) for persistence boundaries and [Work with files and artifacts](https://docs.tokenfactory.nebius.com/sandboxes/guides/work-with-files-and-artifacts.md) for transfer workflows.

## API references

* [Python session and inspection methods](https://docs.tokenfactory.nebius.com/sandboxes/sdk/python_sdk/reference/session.md)
* [REST: inspect an image](https://docs.tokenfactory.nebius.com/api-reference/sandboxes/inspect/inspect-an-image.md)
* [REST: list files](https://docs.tokenfactory.nebius.com/api-reference/sandboxes/inspect/list-files-in-image.md)
* [REST: download a file](https://docs.tokenfactory.nebius.com/api-reference/sandboxes/inspect/download-a-file-from-image.md)
* [REST: download an archive](https://docs.tokenfactory.nebius.com/api-reference/sandboxes/inspect/download-a-file-or-a-directory-from-image-as-tar-archive.md)
