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

<a id="contree_sdk.sdk.objects.image.ContreeImage" />

## `class ContreeImage`

```python theme={null}
class contree_sdk.sdk.objects.image.ContreeImage(client, uuid, tag)
```

<div className="pl-4 ml-1 my-4">
  ### Attributes

  <a id="contree_sdk.sdk.objects.image.ContreeImage.elapsed" />

  <ResponseField name="elapsed" type="timedelta">
    Time elapsed during execution.
  </ResponseField>

  <a id="contree_sdk.sdk.objects.image.ContreeImage.exit_code" />

  <ResponseField name="exit_code" type="int">
    Exit code of the executed command.
  </ResponseField>

  <a id="contree_sdk.sdk.objects.image.ContreeImage.result" />

  <ResponseField name="result" type="ContreeResult">
    Execution result. Only available after successful execution.

    * **Raises** — **RuntimeError** – If the result hasn’t been set.
  </ResponseField>

  <a id="contree_sdk.sdk.objects.image.ContreeImage.state" />

  <ResponseField name="state" type="ImageState">
    Current state of the image in the execution lifecycle.
  </ResponseField>

  <a id="contree_sdk.sdk.objects.image.ContreeImage.stderr" />

  <ResponseField name="stderr" type="str | bytes | Path | IO[str] | IO[bytes] | IOBase | Literal[-1]">
    Stderr output from the execution.
  </ResponseField>

  <a id="contree_sdk.sdk.objects.image.ContreeImage.stdin" />

  <ResponseField name="stdin" type="IO | IOBase | None">
    Configured stdin source.
  </ResponseField>

  <a id="contree_sdk.sdk.objects.image.ContreeImage.stdout" />

  <ResponseField name="stdout" type="str | bytes | Path | IO[str] | IO[bytes] | IOBase | Literal[-1]">
    Stdout output from the execution.
  </ResponseField>

  <a id="contree_sdk.sdk.objects.image.ContreeImage.uuid" />

  <ResponseField name="uuid" type="UUID | None">
    Unique identifier of the image.
  </ResponseField>

  <a id="contree_sdk.sdk.objects.image.ContreeImage.tag" />

  <ResponseField name="tag" type="str | None">
    Optional tag associated with the image.
  </ResponseField>

  ### Methods

  <a id="contree_sdk.sdk.objects.image.ContreeImage.apply_files" />

  #### `apply_files()`

  ```python theme={null}
  async def apply_files(*args, files) -> TypeVar(_T, bound= _ImageLikeBase)
  ```

  Upload files into a new image derived from this one.

  <ParamField path="*args" type="str | Path | UploadFileSpec | list[str | Path | UploadFileSpec] | dict[str, str | Path | UploadFileSpec]">
    Files to upload.
  </ParamField>

  <ParamField path="files" type="list[str | Path | UploadFileSpec] | dict[str, str | Path | UploadFileSpec] | None" default="None">
    Files as a list or a dict mapping destination paths to sources.
    When both args and files are provided, they are merged.
  </ParamField>

  <ResponseField name="returns" type="TypeVar(_T, bound= _ImageLikeBase)">
    New image with the uploaded files baked in.
  </ResponseField>

  <a id="contree_sdk.sdk.objects.image.ContreeImage.download" />

  #### `download()`

  ```python theme={null}
  async def download(image_path, local_path) -> Path | None
  ```

  Download a file from the image to local filesystem.

  <ParamField path="image_path" type="str | PurePosixPath" required>
    Path to the file inside the image.
  </ParamField>

  <ParamField path="local_path" type="str | Path | None" default="None">
    Local destination path. Defaults to filename from image\_path.
  </ParamField>

  <ResponseField name="returns" type="Path | None">
    Path to the downloaded file.
  </ResponseField>

  <a id="contree_sdk.sdk.objects.image.ContreeImage.ls" />

  #### `ls()`

  ```python theme={null}
  async def ls(path) -> list[ImageFile | ImageDirectory]
  ```

  List files and directories at the given path.

  <ParamField path="path" type="str | PurePosixPath" default="'/'">
    Path inside the image to list.
  </ParamField>

  <ResponseField name="returns" type="list[ImageFile | ImageDirectory]">
    list\[[`ImageFile`](./image_fs#contree_sdk.sdk.objects.image_fs.ImageFile) | [`ImageDirectory`](./image_fs#contree_sdk.sdk.objects.image_fs.ImageDirectory)]

    List of ImageFile and ImageDirectory objects.
  </ResponseField>

  <a id="contree_sdk.sdk.objects.image.ContreeImage.read" />

  #### `read()`

  ```python theme={null}
  async def read(image_path) -> bytes
  ```

  Read file contents from the image.

  <ParamField path="image_path" type="str | PurePosixPath" required>
    Path to the file inside the image.
  </ParamField>

  <ResponseField name="returns" type="bytes">
    File contents as bytes.
  </ResponseField>

  <a id="contree_sdk.sdk.objects.image.ContreeImage.run" />

  #### `run()`

  ```python theme={null}
  def run(command, *, shell, args, env, cwd, hostname, stdin, stdout, stderr, tag, files, timeout, disposable, truncate_output_at) -> TypeVar(_T, bound= _ImageLikeBase)
  ```

  Prepare image for command execution.

  <ParamField path="command" type="str | None" default="None">
    Command to execute (mutually exclusive with shell).
  </ParamField>

  <ParamField path="shell" type="str | None" default="None">
    Shell command string (mutually exclusive with command).
  </ParamField>

  <ParamField path="args" type="Iterable[str] | None" default="None">
    Command arguments.
  </ParamField>

  <ParamField path="env" type="dict[str, str] | None" default="None">
    Environment variables.
  </ParamField>

  <ParamField path="cwd" type="str | None" default="None">
    Working directory inside the image.
  </ParamField>

  <ParamField path="hostname" type="str | None" default="None">
    Hostname for the container.
  </ParamField>

  <ParamField path="stdin" type="str | bytes | Path | IO[str] | IO[bytes] | IOBase | Literal[-1] | None" default="None">
    Input source.
  </ParamField>

  <ParamField path="stdout" type="str | bytes | Path | IO[str] | IO[bytes] | IOBase | Literal[-1] | type[str | bytes] | None" default="None">
    Output destination for stdout.
  </ParamField>

  <ParamField path="stderr" type="str | bytes | Path | IO[str] | IO[bytes] | IOBase | Literal[-1] | type[str | bytes] | None" default="None">
    Output destination for stderr.
  </ParamField>

  <ParamField path="tag" type="str | None" default="None">
    Tag for the resulting image.
  </ParamField>

  <ParamField path="files" type="list[str | Path | UploadFileSpec] | dict[str, str | Path | UploadFileSpec] | None" default="None">
    Files to upload into the image.
  </ParamField>

  <ParamField path="timeout" type="float | timedelta | None" default="None">
    Execution timeout in seconds or as timedelta.
  </ParamField>

  <ParamField path="disposable" type="bool" default="True">
    If True, image is discarded after execution.
  </ParamField>

  <ParamField path="truncate_output_at" type="int | None" default="None">
    number of bytes to truncate stdout and stderr. Defaults to default\_truncate\_output\_at
  </ParamField>

  <ResponseField name="returns" type="TypeVar(_T, bound= _ImageLikeBase)">
    New image instance configured for execution.
  </ResponseField>

  <ResponseField name="raises">
    **DisposableImageRunError** – If attempting to run on a disposed image.
  </ResponseField>

  <ResponseField name="raises">
    **ValueError** – If neither command nor shell is provided.
  </ResponseField>

  <a id="contree_sdk.sdk.objects.image.ContreeImage.session" />

  #### `session()`

  ```python theme={null}
  def session() -> ContreeSession
  ```

  <ResponseField name="returns" type="ContreeSession">
    [`ContreeSession`](./session#contree_sdk.sdk.objects.session.ContreeSession)
  </ResponseField>

  <a id="contree_sdk.sdk.objects.image.ContreeImage.tag_as" />

  #### `tag_as()`

  ```python theme={null}
  async def tag_as(tag) -> TypeVar(_T, bound= _ImageLikeBase)
  ```

  Tag this image with the specified tag, or remove the tag if None.

  <ParamField path="tag" type="str | None" required>
    Tag name to apply to the image, or None to remove the tag.
  </ParamField>

  <ResponseField name="returns" type="TypeVar(_T, bound= _ImageLikeBase)">
    New instance with updated tag.
  </ResponseField>

  <a id="contree_sdk.sdk.objects.image.ContreeImage.untag" />

  #### `untag()`

  ```python theme={null}
  async def untag() -> TypeVar(_T, bound= _ImageLikeBase)
  ```

  Remove the tag from this image.

  <ResponseField name="returns" type="TypeVar(_T, bound= _ImageLikeBase)">
    New instance with tag set to None.
  </ResponseField>
</div>

<a id="contree_sdk.sdk.objects.image.ContreeImageSync" />

## `class ContreeImageSync`

```python theme={null}
class contree_sdk.sdk.objects.image.ContreeImageSync(client, uuid, tag)
```

<div className="pl-4 ml-1 my-4">
  ### Attributes

  <a id="contree_sdk.sdk.objects.image.ContreeImageSync.elapsed" />

  <ResponseField name="elapsed" type="timedelta">
    Time elapsed during execution.
  </ResponseField>

  <a id="contree_sdk.sdk.objects.image.ContreeImageSync.exit_code" />

  <ResponseField name="exit_code" type="int">
    Exit code of the executed command.
  </ResponseField>

  <a id="contree_sdk.sdk.objects.image.ContreeImageSync.result" />

  <ResponseField name="result" type="ContreeResult">
    Execution result. Only available after successful execution.

    * **Raises** — **RuntimeError** – If the result hasn’t been set.
  </ResponseField>

  <a id="contree_sdk.sdk.objects.image.ContreeImageSync.state" />

  <ResponseField name="state" type="ImageState">
    Current state of the image in the execution lifecycle.
  </ResponseField>

  <a id="contree_sdk.sdk.objects.image.ContreeImageSync.stderr" />

  <ResponseField name="stderr" type="str | bytes | Path | IO[str] | IO[bytes] | IOBase | Literal[-1]">
    Stderr output from the execution.
  </ResponseField>

  <a id="contree_sdk.sdk.objects.image.ContreeImageSync.stdin" />

  <ResponseField name="stdin" type="IO | IOBase | None">
    Configured stdin source.
  </ResponseField>

  <a id="contree_sdk.sdk.objects.image.ContreeImageSync.stdout" />

  <ResponseField name="stdout" type="str | bytes | Path | IO[str] | IO[bytes] | IOBase | Literal[-1]">
    Stdout output from the execution.
  </ResponseField>

  <a id="contree_sdk.sdk.objects.image.ContreeImageSync.uuid" />

  <ResponseField name="uuid" type="UUID | None">
    Unique identifier of the image.
  </ResponseField>

  <a id="contree_sdk.sdk.objects.image.ContreeImageSync.tag" />

  <ResponseField name="tag" type="str | None">
    Optional tag associated with the image.
  </ResponseField>

  ### Methods

  <a id="contree_sdk.sdk.objects.image.ContreeImageSync.apply_files" />

  #### `apply_files()`

  ```python theme={null}
  def apply_files(*args, files) -> TypeVar(_T, bound= _ImageLikeBase)
  ```

  Upload files into a new image derived from this one.

  <ParamField path="*args" type="str | Path | UploadFileSpec | list[str | Path | UploadFileSpec] | dict[str, str | Path | UploadFileSpec]">
    Files to upload.
  </ParamField>

  <ParamField path="files" type="list[str | Path | UploadFileSpec] | dict[str, str | Path | UploadFileSpec] | None" default="None">
    Files as a list or a dict mapping destination paths to sources.
    When both args and files are provided, they are merged.
  </ParamField>

  <ResponseField name="returns" type="TypeVar(_T, bound= _ImageLikeBase)">
    New image with the uploaded files baked in.
  </ResponseField>

  <a id="contree_sdk.sdk.objects.image.ContreeImageSync.download" />

  #### `download()`

  ```python theme={null}
  def download(image_path, local_path) -> Path | None
  ```

  Download a file from the image to local filesystem.

  <ParamField path="image_path" type="str | PurePosixPath" required>
    Path to the file inside the image.
  </ParamField>

  <ParamField path="local_path" type="str | Path | None" default="None">
    Local destination path. Defaults to filename from image\_path.
  </ParamField>

  <ResponseField name="returns" type="Path | None">
    Path to the downloaded file.
  </ResponseField>

  <a id="contree_sdk.sdk.objects.image.ContreeImageSync.ls" />

  #### `ls()`

  ```python theme={null}
  def ls(path) -> list[ImageFileSync | ImageDirectorySync]
  ```

  List files and directories at the given path.

  <ParamField path="path" type="str | PurePosixPath" default="'/'">
    Path inside the image to list.
  </ParamField>

  <ResponseField name="returns" type="list[ImageFileSync | ImageDirectorySync]">
    list\[[`ImageFileSync`](./image_fs#contree_sdk.sdk.objects.image_fs.ImageFileSync) | [`ImageDirectorySync`](./image_fs#contree_sdk.sdk.objects.image_fs.ImageDirectorySync)]

    List of ImageFileSync and ImageDirectorySync objects.
  </ResponseField>

  <a id="contree_sdk.sdk.objects.image.ContreeImageSync.popen" />

  #### `popen()`

  ```python theme={null}
  def popen(args, *, stdin, input, stdout, stderr, shell, cwd, timeout, check, text, env) -> ContreeProcessSync
  ```

  Run a command with subprocess-like interface.

  <ParamField path="args" type="list[str] | str | None" default="None">
    Command and arguments list.
  </ParamField>

  <ParamField path="stdin" type="str | bytes | Path | IO[str] | IO[bytes] | IOBase | Literal[-1] | None" default="None">
    Input source.
  </ParamField>

  <ParamField path="input" type="str | bytes | Path | IO[str] | IO[bytes] | IOBase | Literal[-1] | None" default="None">
    Alternative input source (alias for stdin).
  </ParamField>

  <ParamField path="stdout" type="str | bytes | Path | IO[str] | IO[bytes] | IOBase | Literal[-1] | None" default="None">
    Output destination for stdout.
  </ParamField>

  <ParamField path="stderr" type="str | bytes | Path | IO[str] | IO[bytes] | IOBase | Literal[-1] | None" default="None">
    Output destination for stderr.
  </ParamField>

  <ParamField path="shell" type="bool" default="False">
    If True, treat args as shell command.
  </ParamField>

  <ParamField path="cwd" type="str | None" default="None">
    Working directory inside the image.
  </ParamField>

  <ParamField path="timeout" type="float | None" default="None">
    Execution timeout in seconds.
  </ParamField>

  <ParamField path="check" type="bool" default="False">
    If True, raise on non-zero exit code.
  </ParamField>

  <ParamField path="text" type="bool | None" default="None">
    If True, decode output as text.
  </ParamField>

  <ParamField path="env" type="dict[str, str] | None" default="None">
    Environment variables.
  </ParamField>

  <ResponseField name="returns" type="ContreeProcessSync">
    [`ContreeProcessSync`](./subprocess#contree_sdk.sdk.objects.subprocess.ContreeProcessSync)

    ContreeProcessSync object with execution results.
  </ResponseField>

  <a id="contree_sdk.sdk.objects.image.ContreeImageSync.read" />

  #### `read()`

  ```python theme={null}
  def read(image_path) -> bytes
  ```

  Read file contents from the image.

  <ParamField path="image_path" type="str | PurePosixPath" required>
    Path to the file inside the image.
  </ParamField>

  <ResponseField name="returns" type="bytes">
    File contents as bytes.
  </ResponseField>

  <a id="contree_sdk.sdk.objects.image.ContreeImageSync.run" />

  #### `run()`

  ```python theme={null}
  def run(command, *, shell, args, env, cwd, hostname, stdin, stdout, stderr, tag, files, timeout, disposable, truncate_output_at) -> TypeVar(_T, bound= _ImageLikeBase)
  ```

  Prepare image for command execution.

  <ParamField path="command" type="str | None" default="None">
    Command to execute (mutually exclusive with shell).
  </ParamField>

  <ParamField path="shell" type="str | None" default="None">
    Shell command string (mutually exclusive with command).
  </ParamField>

  <ParamField path="args" type="Iterable[str] | None" default="None">
    Command arguments.
  </ParamField>

  <ParamField path="env" type="dict[str, str] | None" default="None">
    Environment variables.
  </ParamField>

  <ParamField path="cwd" type="str | None" default="None">
    Working directory inside the image.
  </ParamField>

  <ParamField path="hostname" type="str | None" default="None">
    Hostname for the container.
  </ParamField>

  <ParamField path="stdin" type="str | bytes | Path | IO[str] | IO[bytes] | IOBase | Literal[-1] | None" default="None">
    Input source.
  </ParamField>

  <ParamField path="stdout" type="str | bytes | Path | IO[str] | IO[bytes] | IOBase | Literal[-1] | type[str | bytes] | None" default="None">
    Output destination for stdout.
  </ParamField>

  <ParamField path="stderr" type="str | bytes | Path | IO[str] | IO[bytes] | IOBase | Literal[-1] | type[str | bytes] | None" default="None">
    Output destination for stderr.
  </ParamField>

  <ParamField path="tag" type="str | None" default="None">
    Tag for the resulting image.
  </ParamField>

  <ParamField path="files" type="list[str | Path | UploadFileSpec] | dict[str, str | Path | UploadFileSpec] | None" default="None">
    Files to upload into the image.
  </ParamField>

  <ParamField path="timeout" type="float | timedelta | None" default="None">
    Execution timeout in seconds or as timedelta.
  </ParamField>

  <ParamField path="disposable" type="bool" default="True">
    If True, image is discarded after execution.
  </ParamField>

  <ParamField path="truncate_output_at" type="int | None" default="None">
    number of bytes to truncate stdout and stderr. Defaults to default\_truncate\_output\_at
  </ParamField>

  <ResponseField name="returns" type="TypeVar(_T, bound= _ImageLikeBase)">
    New image instance configured for execution.
  </ResponseField>

  <ResponseField name="raises">
    **DisposableImageRunError** – If attempting to run on a disposed image.
  </ResponseField>

  <ResponseField name="raises">
    **ValueError** – If neither command nor shell is provided.
  </ResponseField>

  <a id="contree_sdk.sdk.objects.image.ContreeImageSync.session" />

  #### `session()`

  ```python theme={null}
  def session() -> ContreeSessionSync
  ```

  <ResponseField name="returns" type="ContreeSessionSync">
    [`ContreeSessionSync`](./session#contree_sdk.sdk.objects.session.ContreeSessionSync)
  </ResponseField>

  <a id="contree_sdk.sdk.objects.image.ContreeImageSync.tag_as" />

  #### `tag_as()`

  ```python theme={null}
  def tag_as(tag) -> TypeVar(_T, bound= _ImageLikeBase)
  ```

  Tag this image with the specified tag, or remove the tag if None.

  <ParamField path="tag" type="str | None" required>
    Tag name to apply to the image, or None to remove the tag.
  </ParamField>

  <ResponseField name="returns" type="TypeVar(_T, bound= _ImageLikeBase)">
    New instance with updated tag.
  </ResponseField>

  <a id="contree_sdk.sdk.objects.image.ContreeImageSync.untag" />

  #### `untag()`

  ```python theme={null}
  def untag() -> TypeVar(_T, bound= _ImageLikeBase)
  ```

  Remove the tag from this image.

  <ResponseField name="returns" type="TypeVar(_T, bound= _ImageLikeBase)">
    New instance with tag set to None.
  </ResponseField>

  <a id="contree_sdk.sdk.objects.image.ContreeImageSync.wait" />

  #### `wait()`

  ```python theme={null}
  def wait() -> TypeVar(_T, bound= _ImageLikeSync)
  ```

  Execute the prepared command and wait for completion.

  <ResponseField name="returns" type="TypeVar(_T, bound= _ImageLikeSync)">
    New image instance with execution results.
  </ResponseField>
</div>