---
title: Save Image
---

import { SaveImageNav } from './SaveImageCards'

# Save Image

<SaveImageNav />

The **Save Image** feature captures the current state of a running TIR instance as a Docker image and pushes it to the E2E Container Registry. This enables you to preserve, reproduce, and share your environment without reconfiguring it from scratch.

Saved images can be used to launch new instances with identical environments, or pulled locally via Docker for further development and testing.

## When to Use Save Image

Save Image is recommended in the following situations:

- Preserve a configured environment before making significant changes to it
- Standardize a runtime environment across project members
- Create a versioned checkpoint before upgrading frameworks or dependencies
- Eliminate repeated environment setup when launching new instances
- Maintain a consistent base environment for recurring workloads

## How Save Image Works

When you trigger Save Image, TIR commits the writable container layer of the running instance into a new Docker image and pushes it to your configured Container Registry under Platform Services. The operation runs against the live container filesystem and does not require the instance to be stopped.

:::info
Save Image captures the container layer only. Mounted volumes, workspace directories, and dataset paths are not part of the resulting image.
:::

### What Is Captured

| Included in Image | Not Included |
|-------------------|--------------|
| Installed Python packages (pip, conda) | Workspace volume (`/home/jovyan`) |
| System packages (apt/yum installs) | Datasets mounted to `/data` |
| Custom binaries in system paths | Local NVMe data (`/mnt/local`) |
| Environment variables (baked into the layer) | Shared File System mounts |
| Modified configuration files (.bashrc, Jupyter) | Jupyter notebooks and project files |
| Scripts placed in `/usr/local/bin` | Model checkpoints in workspace |

:::warning
Files in `/home/jovyan`, `/data`, and `/mnt/local` are not included in the saved image. Back up important data to E2E Object Storage (EOS) or a Git repository before running Save Image.
:::

## Prerequisites

Before using Save Image, confirm the following are available in your project:

<div style={{display:'grid', gridTemplateColumns:'repeat(auto-fit, minmax(240px, 1fr))', gap:'16px', margin:'16px 0 24px'}}>
  <div style={{border:'1px solid var(--ifm-color-emphasis-300)', borderRadius:'8px', padding:'20px'}}>
    <div style={{fontWeight:700, fontSize:'11px', letterSpacing:'0.08em', color:'var(--ifm-color-primary)', marginBottom:'10px', textTransform:'uppercase'}}>Required</div>
    <div style={{fontWeight:600, fontSize:'15px', marginBottom:'8px'}}>Active TIR Instance</div>
    <div style={{fontSize:'14px', color:'var(--ifm-color-emphasis-700)', lineHeight:'1.6'}}>A running instance in your TIR project that you want to snapshot.</div>
  </div>
  <div style={{border:'1px solid var(--ifm-color-emphasis-300)', borderRadius:'8px', padding:'20px'}}>
    <div style={{fontWeight:700, fontSize:'11px', letterSpacing:'0.08em', color:'var(--ifm-color-primary)', marginBottom:'10px', textTransform:'uppercase'}}>Required</div>
    <div style={{fontWeight:600, fontSize:'15px', marginBottom:'8px'}}>Container Registry</div>
    <div style={{fontSize:'14px', color:'var(--ifm-color-emphasis-700)', lineHeight:'1.6'}}>An E2E Container Registry configured under <strong>Platform Services</strong> in your project.</div>
  </div>
</div>

:::warning
A Container Registry must exist in your project before Save Image can be used. Navigate to **Platform Services &gt; Container Registry** to create one if you have not done so.
:::

## Step-by-Step Process

Once your Container Registry is configured, follow these steps to save your instance environment.

<div style={{display:'flex', flexDirection:'column', gap:'12px', margin:'24px 0'}}>

  <div style={{display:'flex', gap:'0', border:'1px solid var(--ifm-color-emphasis-300)', borderRadius:'8px', overflow:'hidden'}}>
    <div style={{background:'var(--ifm-color-primary)', color:'#ffffff', minWidth:'48px', display:'flex', alignItems:'flex-start', justifyContent:'center', paddingTop:'20px', fontWeight:700, fontSize:'14px', flexShrink:0}}>1</div>
    <div style={{padding:'18px 24px', flex:1}}>
      <div style={{fontWeight:700, marginBottom:'8px', fontSize:'15px'}}>Open Instance Actions</div>
      <div style={{fontSize:'14px', color:'var(--ifm-color-emphasis-800)', lineHeight:'1.6'}}>Navigate to <strong>Instances</strong> from the left sidebar. Locate your instance and open the <strong>Actions</strong> menu from the instance row or the instance detail page.</div>
    </div>
  </div>

  <div style={{display:'flex', gap:'0', border:'1px solid var(--ifm-color-emphasis-300)', borderRadius:'8px', overflow:'hidden'}}>
    <div style={{background:'var(--ifm-color-primary)', color:'#ffffff', minWidth:'48px', display:'flex', alignItems:'flex-start', justifyContent:'center', paddingTop:'20px', fontWeight:700, fontSize:'14px', flexShrink:0}}>2</div>
    <div style={{padding:'18px 24px', flex:1}}>
      <div style={{fontWeight:700, marginBottom:'8px', fontSize:'15px'}}>Select Save Image</div>
      <div style={{fontSize:'14px', color:'var(--ifm-color-emphasis-800)', lineHeight:'1.6'}}>Click <strong>Save Image</strong> from the Actions menu. A configuration dialog will open.</div>
    </div>
  </div>

  <div style={{display:'flex', gap:'0', border:'1px solid var(--ifm-color-emphasis-300)', borderRadius:'8px', overflow:'hidden'}}>
    <div style={{background:'var(--ifm-color-primary)', color:'#ffffff', minWidth:'48px', display:'flex', alignItems:'flex-start', justifyContent:'center', paddingTop:'20px', fontWeight:700, fontSize:'14px', flexShrink:0}}>3</div>
    <div style={{padding:'18px 24px', flex:1}}>
      <div style={{fontWeight:700, marginBottom:'8px', fontSize:'15px'}}>Configure Image Details</div>
      <div style={{fontSize:'14px', color:'var(--ifm-color-emphasis-800)', lineHeight:'1.6', marginBottom:'16px'}}>Complete the fields in the Save Image dialog:</div>

| Field | Description |
|-------|-------------|
| **Image Name** | A unique identifier for the image. Use lowercase letters, numbers, and hyphens only (for example, `pytorch-env-v1`). |
| **Tag** | A version label for the image (for example, `v1.0`). Defaults to `latest` if left blank. |
| **Registry** | The Container Registry namespace where the image will be stored. Select from the dropdown. |

    </div>
  </div>

  <div style={{display:'flex', gap:'0', border:'1px solid var(--ifm-color-emphasis-300)', borderRadius:'8px', overflow:'hidden'}}>
    <div style={{background:'var(--ifm-color-primary)', color:'#ffffff', minWidth:'48px', display:'flex', alignItems:'flex-start', justifyContent:'center', paddingTop:'20px', fontWeight:700, fontSize:'14px', flexShrink:0}}>4</div>
    <div style={{padding:'18px 24px', flex:1}}>
      <div style={{fontWeight:700, marginBottom:'8px', fontSize:'15px'}}>Confirm and Initiate</div>
      <div style={{fontSize:'14px', color:'var(--ifm-color-emphasis-800)', lineHeight:'1.6'}}>Review the configuration and click <strong>Save Image</strong> to begin. A confirmation banner will appear and the image push will start. Instance management actions are restricted while the save is in progress.</div>
    </div>
  </div>

  <div style={{display:'flex', gap:'0', border:'1px solid var(--ifm-color-emphasis-300)', borderRadius:'8px', overflow:'hidden'}}>
    <div style={{background:'var(--ifm-color-primary)', color:'#ffffff', minWidth:'48px', display:'flex', alignItems:'flex-start', justifyContent:'center', paddingTop:'20px', fontWeight:700, fontSize:'14px', flexShrink:0}}>5</div>
    <div style={{padding:'18px 24px', flex:1}}>
      <div style={{fontWeight:700, marginBottom:'8px', fontSize:'15px'}}>Verify the Image</div>
      <div style={{fontSize:'14px', color:'var(--ifm-color-emphasis-800)', lineHeight:'1.6'}}>Once the push completes, navigate to <strong>Platform Services &gt; Container Registry</strong> and open your namespace. The saved image will appear in the repository list with its tag, size, and push date.</div>
    </div>
  </div>

</div>

:::danger
Do not stop, restart, or delete the instance while a save is in progress. Doing so may result in a corrupt or incomplete image.
:::

:::note
Save time varies based on environment size. Instances with large ML stacks such as PyTorch, TensorFlow, or JAX may take several minutes to complete.
:::

## Using a Saved Image

### Launch a New TIR Instance

1. Navigate to **Instances** and click **Create Instance**.
2. In the container image section, select **Use Custom Image**.
3. Set Image Type to **Private** and select your **Registry Namespace** from the dropdown.
4. Select the saved image from the list and click **Launch**.

### Pull the Image via Docker

Authenticate and pull the image using the Docker CLI:

```bash
# Authenticate to the E2E Container Registry
docker login registry.e2enetworks.net -u <your_username> -p <your_password>

# Pull the saved image
docker pull registry.e2enetworks.net/<namespace>/<image-name>:<tag>

# Example
docker pull registry.e2enetworks.net/my-project-images/pytorch-env-v1:latest
```

:::info
Your Docker login credentials are available in the Container Registry. Navigate to **Platform Services &gt; Container Registry**, select your registry namespace, and click **Commands** to retrieve a pre-filled login command.
:::

## Managing Saved Images

### View Saved Images

Navigate to **Platform Services &gt; Container Registry** and select your registry namespace. All images are listed with their tags, sizes, push dates, and scan status.

### Delete an Image

1. In the registry namespace view, click the image name.
2. Click **Delete Image**.
3. Confirm the deletion in the dialog.

<br />

:::warning
Image and tag deletions are permanent. Verify that no running instances or active workloads reference the image before proceeding. There is no recovery option.
:::

## Important Considerations

### Troubleshooting

| Issue | Resolution |
|-------|------------|
| **Save Image option is unavailable** | Save Image is only available for running instances. Ensure the instance is in a running state before initiating the operation. |
| **Image save fails or exceeds expected duration** | Save duration depends on the installed environment size. Large environments may require additional time to complete. |
| **Cannot pull image via Docker** | Verify your credentials. Navigate to **Platform Services &gt; Container Registry** and click **Commands** for an updated login command. |
| **New instance does not reflect expected changes** | Confirm the correct image tag was selected. Workspace data in `/home/jovyan` is not part of the image. |
| **Authentication errors during image push** | Validate the base64 token in `config.json` and confirm the registry URL exactly matches your namespace at `registry.e2enetworks.net/<ns>`. |
| **Image not visible in registry after save** | Wait a few minutes and refresh the page. If the image remains missing, check the instance Events tab for push-related error logs. |

### Best Practices

**Use descriptive, versioned image names.** A name like `llm-finetune-pytorch21-v2` is more useful than `myimage` when managing multiple environment versions over time.

**Save after every significant environment change.** Treat saved images as environment checkpoints. Saving regularly gives you reliable rollback points before major modifications.

**Keep workspace data separate from images.** Datasets, model checkpoints, and notebooks belong in `/home/jovyan`, EOS buckets, or a Git repository. They should not be stored in the container layer.

**Use semantic version tags.** Tagging images with `v1.0`, `v1.1`, and so on is preferable to overwriting `latest` on every save. This preserves rollback capability across versions.

**Prune unused images periodically.** Remove images that have not been referenced in 90 or more days to keep registry storage under control.

**Validate images before production use.** Launch a small instance from a newly saved image and verify the environment behaves as expected before integrating it into shared workflows.

:::tip
To share a saved image, provide teammates with the Docker pull command for the relevant namespace and tag. Ensure your Container Registry namespace permissions allow access for the intended users.
:::



---