---
title: "TIR Instance"
description: "A TIR Instance is a GPU or CPU container in TIR with JupyterLab or SSH, a workspace that keeps your files, and a choice of ready-made images."
content_type: "overview"
product: "tir-instance"
platform: "TIR"
url: "/tir/tir-instance/"
---

# TIR Instance

<!-- cspell:ignore MPNN jovyan -->

A TIR Instance is a GPU or CPU machine set up for machine learning work. You pick an image with the framework you use, such as PyTorch, TensorFlow, Transformers, or vLLM, and a plan with the GPUs you need. Then you work in JupyterLab in your browser, or over SSH from your own terminal.

Use an instance to explore data in notebooks, train and fine-tune models, run a model behind a
small web app, or build and test your own environment before you share it with your team. Each
instance is a container in your TIR project, and its workspace at `/home/jovyan` keeps your
notebooks, data, and checkpoints through restarts, stops, and starts.

## Where to find it

In TIR, open your project. In the side menu, under **Compute**, select **Containers (Instances)**.
Your instances are listed in **Manage Instances**, and **Create Instance** starts a new one.

## How it fits together

```mermaid
flowchart LR
    A[Choose an image] --> C[Instance]
    B[Choose a plan] --> C
    C --> D[Open JupyterLab]
    C --> E[Connect over SSH]
    C --> F[Mount datasets and file systems]
    C --> G[Save it as an image]
```

You choose an image and a plan, and TIR starts the instance from them. Once it is running, you open
JupyterLab in your browser or connect over SSH. To bring in data that lives outside the instance,
you mount datasets and file systems on it. When the instance has the packages you need, you can save
it as an image and start new instances from it.

The image decides what the instance starts with:

| Image     | What you get                                                                                                | Choose it when                                                                                  |
| --------- | ----------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| Pre-built | An image maintained by E2E, with a machine learning framework and an app such as JupyterLab                 | You want to start working in your browser straight away                                         |
| Base OS   | An operating system with no app, which you reach over SSH                                                   | You want to install and set up everything yourself                                              |
| Custom    | Your own image from your project's Container Registry, or a public image from a registry such as Docker Hub | You need a setup beyond what the pre-built images offer, or one environment for your whole team |

The plan sets the instance's GPUs, vCPUs, and memory. An instance runs on a GPU plan, a CPU plan, or
your own TIR private cluster.

## What you can do

### Create and connect

- [Create an instance](/tir/tir-instance/how-to/create-an-instance/) from a pre-built or Base OS
  image, with each choice explained.
- [Create an instance from your own
  image](/tir/tir-instance/how-to/create-an-instance-from-your-own-image/), from your Container
  Registry or a public registry.
- [Connect to an instance over SSH](/tir/tir-instance/how-to/connect-to-an-instance-over-ssh/) from
  a terminal or VS Code.
- [Open a port on an instance](/tir/tir-instance/how-to/open-a-port-on-an-instance/) so an app you
  run can be reached from outside.
- [Manage IP addresses on an
  instance](/tir/tir-instance/how-to/manage-ip-addresses-on-an-instance/): reserved IPs, the public
  IP, and a VPC IP.
- [Run start scripts on an instance](/tir/tir-instance/how-to/run-start-scripts-on-an-instance/)
  each time it starts.

### Run and change an instance

- [Stop, start, and restart an
  instance](/tir/tir-instance/how-to/stop-start-and-restart-an-instance/).
- [Change the plan of an instance](/tir/tir-instance/how-to/change-the-plan-of-an-instance/) to more
  or fewer GPUs, vCPUs, or memory.
- [Update the image of an instance](/tir/tir-instance/how-to/update-the-image-of-an-instance/)
  and keep the same instance.
- [Increase the workspace size](/tir/tir-instance/how-to/increase-the-workspace-size/) when
  `/home/jovyan` fills up.
- [Convert an instance to a committed
  plan](/tir/tir-instance/how-to/convert-an-instance-to-committed/) to pay for a fixed term upfront.
- [Clone an instance](/tir/tir-instance/how-to/clone-an-instance/) to launch a copy of its settings.
- [Delete an instance](/tir/tir-instance/how-to/delete-an-instance/) when you have finished with it.

### Keep your environment

- [Save an instance as an image](/tir/tir-instance/how-to/save-an-instance-as-an-image/) to keep the
  packages you installed and launch new instances from them.
- [Build container images with
  BuildKit](/tir/tir-instance/how-to/build-container-images-with-buildkit/) from a Dockerfile, on the
  instance itself.

### Work with data

- [Mount datasets and file systems on an
  instance](/tir/tir-instance/how-to/mount-datasets-and-file-systems/).
- [Copy files to and from an
  instance](/tir/tir-instance/how-to/copy-files-to-and-from-an-instance/) with `scp`, `sftp`,
  `rsync`, or JupyterLab.

### Monitor

- [Monitor an instance](/tir/tir-instance/how-to/monitor-an-instance/): its usage charts, logs,
  events, and alerts.

### Guides

- [Use TensorBoard on an instance](/tir/tir-instance/how-to/use-tensorboard-on-an-instance/) and
  [Use Gradio on an instance](/tir/tir-instance/how-to/use-gradio-on-an-instance/), the two add-ons.
- [Access Google Drive from an
  instance](/tir/tir-instance/how-to/access-google-drive-from-an-instance/).
- [Fine-tune Llama 3 with LLaMA
  Factory](/tir/tir-instance/how-to/fine-tune-llama-3-with-llama-factory/).
- [Run AlphaFold2 on an instance](/tir/tir-instance/how-to/run-alphafold2-on-an-instance/) and [Run
  ProteinMPNN on an instance](/tir/tir-instance/how-to/run-proteinmpnn-on-an-instance/) for protein
  structure and design.

You can also create, start, stop, and delete instances through the API. See [the instance operations
in the TIR API](/api/tir/compute/).

## Instance, TIR Virtual Machine, or MyAccount GPU node

A TIR Instance is a container with pre-built machine learning images, JupyterLab, and the
TensorBoard and Gradio add-ons, ready for work as soon as it starts. Only `/home/jovyan` and mounted
storage keep data across restarts, and it runs without `systemd` or a Docker daemon.

A [TIR Virtual Machine](/tir/tir-vm/), under **Compute** > **Virtual Machines**, is a full Linux
virtual machine with its own kernel and root access. Its disk keeps its files across restarts and
stops. Choose it for work that changes the operating system itself.

A [MyAccount GPU node](/myaccount/gpu-node/) is a virtual machine in MyAccount where you choose the
operating system. For how the three compare, see the [TIR Instance FAQ](/tir/tir-instance/faq/).

## Where to start

Start with [Get started with TIR Instances](/tir/tir-instance/get-started/), which launches an
instance and opens JupyterLab on it. [Where your files live on an instance](/tir/tir-instance/concepts/where-your-files-live/) explains which folders keep your work. [Billing options for TIR Instances](/tir/tir-instance/concepts/billing-options/) explains On-Demand, committed, and Spot billing, and [Pre-built images and their versions](/tir/tir-instance/concepts/pre-built-images/) lists every pre-built image. For help with a
problem, see [Troubleshooting TIR Instances](/tir/tir-instance/troubleshooting/tir-instance/), and
for short answers, the [TIR Instance FAQ](/tir/tir-instance/faq/).