> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nova-cloud.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Connecting to an Instance

> Access your GPU instance via SSH or the browser-based WebUI portal.

Once your instance is running, there are two ways to connect: **SSH** for terminal access and **WebUI** for browser-based access. This guide covers both.

## Prerequisites

* A running instance (status shows **Running** in the dashboard)
* For SSH: an SSH key uploaded to your account, or the password you set during instance creation
* For WebUI: an instance created with a supported template (Stable Diffusion, ComfyUI, or Linux Desktop)

## Finding Your Connection Details

1. Go to **My Instances** in the console
2. Find your running instance
3. Click the **Connect** button

<Frame caption="Instance card with Connect button highlighted">
  <img src="https://mintcdn.com/novacloudservicesinc/vyZyT77P0XaT78JA/images/guides/instance-connect-button.png?fit=max&auto=format&n=vyZyT77P0XaT78JA&q=85&s=b9d1a46d2f10c66f21d2787c365417cd" alt="Instance card showing the Connect button" width="1306" height="906" data-path="images/guides/instance-connect-button.png" />
</Frame>

This opens a window showing your SSH details and WebUI status.

<Frame caption="Connection details showing SSH command and WebUI portal status">
  <img src="https://mintcdn.com/novacloudservicesinc/vyZyT77P0XaT78JA/images/guides/connect-window.png?fit=max&auto=format&n=vyZyT77P0XaT78JA&q=85&s=fc4cdf3902ee85573e7ea71de95d7158" alt="Connection details with SSH and WebUI information" width="1400" height="1458" data-path="images/guides/connect-window.png" />
</Frame>

## Connecting via SSH

SSH gives you full terminal access to your instance. This is the primary way to interact with your VM.

### Your SSH Details

| Detail         | Value                                             |
| -------------- | ------------------------------------------------- |
| **IP Address** | Shown after clicking **Connect** on your instance |
| **Username**   | `ubuntu`                                          |
| **Port**       | `22` (default)                                    |

### Connect from Your Terminal

<Tabs>
  <Tab title="Mac">
    Open **Terminal** (Cmd + Space → "Terminal") and run:

    ```bash theme={null}
    ssh ubuntu@<your-vm-ip>
    ```

    Replace `<your-vm-ip>` with the IP address shown after clicking **Connect**.

    <Tip>
      Click the **copy button** in the connection details to copy the full SSH command to your clipboard, ready to paste.
    </Tip>
  </Tab>

  <Tab title="Windows (PowerShell)">
    Open **PowerShell** (Start → "PowerShell") and run:

    ```powershell theme={null}
    ssh ubuntu@<your-vm-ip>
    ```

    Replace `<your-vm-ip>` with the IP address shown after clicking **Connect**.

    <Note>
      Windows 10/11 includes an SSH client by default. If `ssh` is not found, enable it via **Settings → Apps → Optional Features → OpenSSH Client**.
    </Note>
  </Tab>

  <Tab title="Windows (PuTTY)">
    If you use PuTTY instead of the built-in SSH client:

    1. Open **PuTTY**
    2. In **Host Name**, enter: `ubuntu@<your-vm-ip>`
    3. Ensure **Port** is `22` and **Connection type** is **SSH**
    4. Go to **Connection → SSH → Auth → Credentials**
    5. Under "Private key file", browse to your `.ppk` key file
    6. Click **Open** to connect
  </Tab>

  <Tab title="Linux">
    Open a terminal and run:

    ```bash theme={null}
    ssh ubuntu@<your-vm-ip>
    ```

    Replace `<your-vm-ip>` with the IP address shown after clicking **Connect**.
  </Tab>
</Tabs>

### First-Time Connection

When connecting to an instance for the first time, you'll see a host key verification prompt:

```
The authenticity of host '203.0.113.50 (203.0.113.50)' can't be established.
ED25519 key fingerprint is SHA256:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.
Are you sure you want to continue connecting (yes/no/[fingerprint])?
```

Type `yes` and press Enter. This is normal and only happens once per instance. Your computer remembers the host key for future connections.

### Using a Specific SSH Key

If you have multiple SSH keys, specify which one to use:

```bash theme={null}
ssh -i ~/.ssh/id_ed25519 ubuntu@<your-vm-ip>
```

### Connecting with a Password

If you chose password authentication when creating the instance:

```bash theme={null}
ssh ubuntu@<your-vm-ip>
```

You'll be prompted to enter the password you set during creation.

## Connecting via WebUI Portal

The WebUI portal gives you browser-based access to web applications running on your instance. This is available for instances created with specific templates.

### Supported Templates

| ID    | Template                               | WebUI Access                  |
| ----- | -------------------------------------- | ----------------------------- |
| `100` | Ubuntu 22.04 Base                      | Not available                 |
| `101` | Ubuntu 24.04 Base                      | Not available                 |
| `102` | **Stable Diffusion (A1111) + Jupyter** | Automatic1111 WebUI + Jupyter |
| `103` | **ComfyUI + Jupyter**                  | ComfyUI + Jupyter             |
| `104` | **Linux Desktop + Jupyter**            | Desktop environment + Jupyter |

### Accessing the WebUI

1. Go to **My Instances** and click **Connect** on your running instance
2. In the connection details window, find the **WebUI Portal** section
3. Click **Open WebUI** to launch the portal in a new browser tab

<Frame caption="WebUI portal status showing Ready">
  <img src="https://mintcdn.com/novacloudservicesinc/vyZyT77P0XaT78JA/images/guides/webui-portal-ready.png?fit=max&auto=format&n=vyZyT77P0XaT78JA&q=85&s=45b6abeb84c099c9fd36e7aae3f22425" alt="WebUI portal showing Ready status with Open button" width="1328" height="342" data-path="images/guides/webui-portal-ready.png" />
</Frame>

### WebUI Status

The portal can be in one of three states:

| Status           | Meaning                                                                             |
| ---------------- | ----------------------------------------------------------------------------------- |
| **Ready**        | The WebUI is ready to use — click to open                                           |
| **Initializing** | The portal is starting up (typically 30–60 seconds after boot) — wait and try again |
| **Unavailable**  | This template doesn't include a WebUI, or the instance isn't running                |

<Note>
  The WebUI portal is secured via Cloudflare. It provides authenticated access to web services running inside your VM without needing to open ports manually.
</Note>

## Keeping Your Session Alive

Long SSH sessions can disconnect due to network timeouts. To prevent this, configure your SSH client to send keepalive packets.

### Mac / Linux

Add these lines to your `~/.ssh/config` file:

```
Host *
    ServerAliveInterval 60
    ServerAliveCountMax 3
```

This sends a keepalive packet every 60 seconds and disconnects after 3 missed responses.

### Windows (PowerShell SSH)

Create or edit `C:\Users\YourName\.ssh\config` with the same configuration:

```
Host *
    ServerAliveInterval 60
    ServerAliveCountMax 3
```

## Transferring Files

### Upload Files to Your Instance

<Tabs>
  <Tab title="Mac / Linux">
    Use `scp` to copy files:

    ```bash theme={null}
    # Upload a single file
    scp myfile.txt ubuntu@<your-vm-ip>:~/

    # Upload an entire directory
    scp -r my-folder/ ubuntu@<your-vm-ip>:~/
    ```
  </Tab>

  <Tab title="Windows (PowerShell)">
    PowerShell includes `scp`:

    ```powershell theme={null}
    # Upload a single file
    scp myfile.txt ubuntu@<your-vm-ip>:~/

    # Upload an entire directory
    scp -r my-folder/ ubuntu@<your-vm-ip>:~/
    ```
  </Tab>
</Tabs>

### Download Files from Your Instance

```bash theme={null}
# Download a single file
scp ubuntu@<your-vm-ip>:~/results.csv ./

# Download an entire directory
scp -r ubuntu@<your-vm-ip>:~/output/ ./
```

<Tip>
  For large file transfers, consider using `rsync` for resumable transfers:

  ```bash theme={null}
  rsync -avz --progress ubuntu@<your-vm-ip>:~/large-dataset/ ./local-copy/
  ```
</Tip>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Connection refused">
    * Verify the instance status is **Running** in the dashboard
    * Double-check the IP address — click **Connect** on your instance to find it
    * Wait 1–2 minutes if the instance was just started; SSH may take a moment to be ready
  </Accordion>

  <Accordion title="Permission denied (publickey)">
    Your SSH key doesn't match. Try:

    1. Check which keys are loaded: `ssh-add -l`
    2. Specify the key explicitly: `ssh -i ~/.ssh/id_ed25519 ubuntu@<ip>`
    3. Verify you uploaded the correct public key to Nova Cloud (Account → SSH Keys)

    See the [SSH Keys troubleshooting guide](/guides/ssh-keys#troubleshooting) for more details.
  </Accordion>

  <Accordion title="Connection timed out">
    * Confirm the instance is in **Running** state
    * Newly created instances can take up to 10 minutes to provision — check the status in the dashboard
    * Try stopping and starting the instance from the dashboard
  </Accordion>

  <Accordion title="WebUI shows Initializing for a long time">
    The WebUI portal typically starts within 30–60 seconds. If it's been longer:

    * Try closing and reopening the connection details
    * Stop and start the instance
    * Check if the instance is still **Running** in the dashboard
  </Accordion>

  <Accordion title="Host key verification failed">
    This happens if you've connected to a different instance that previously had the same IP address. Remove the old key:

    ```bash theme={null}
    ssh-keygen -R <your-vm-ip>
    ```

    Then try connecting again.
  </Accordion>
</AccordionGroup>

## What's Next?

<CardGroup cols={2}>
  <Card title="Instance Ports" icon="network-wired" href="/guides/instance-ports">
    Open ports for web services, Jupyter, and custom APIs.
  </Card>

  <Card title="SSH Keys" icon="key" href="/guides/ssh-keys">
    Manage your SSH keys and troubleshoot connection issues.
  </Card>
</CardGroup>