Skip to main content
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 and install the SDK as described in the Python quickstart. 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.
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

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 for persistence boundaries and Work with files and artifacts for transfer workflows.

API references