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

# Choose how to access your Ornn compute

> Ornn offers two access modes for GPU reservations today: VM for a managed image-based environment, and Bare Metal for direct host access. Configure the mode from the reservation detail page.

When you have a confirmed reservation, Ornn lets you choose how your GPU hardware is materialized and made accessible. You set this choice per reservation from the reservation detail page (`/portfolio/[reservationId]`).

## Available access modes

Two access modes are implemented today:

<div className="accesssplit">
  <span className="accesssplit-source">Confirmed reservation</span>

  <span className="accesssplit-stem" />

  <span className="accesssplit-note">set per reservation on the detail page</span>

  <div className="accesssplit-branches">
    <div className="accessmode">
      <h4>VM</h4>

      <p>
        Managed virtual machine on your reserved hardware. Ornn base image (Ubuntu, CUDA, PyTorch)
        or an approved custom image. SSH into the VM.
      </p>
    </div>

    <div className="accessmode">
      <h4>Bare Metal</h4>

      <p>
        Direct SSH to the physical host. No virtualization layer; you manage the software
        environment yourself.
      </p>
    </div>
  </div>
</div>

|                         | VM                                                                    | Bare Metal                                                        |
| ----------------------- | --------------------------------------------------------------------- | ----------------------------------------------------------------- |
| **Use case**            | Most ML training and inference workloads                              | Workloads that need direct hardware control or maximum throughput |
| **Performance profile** | Near-bare-metal; slight virtualization overhead                       | No virtualization, direct physical host                           |
| **Image options**       | Ornn base image (Ubuntu + CUDA + PyTorch) or an approved custom image | No image; you manage the software environment directly            |
| **Recommended for**     | Most Ornn customers                                                   | Advanced users who need full hardware control                     |

<Note>
  Need a cluster instead of a single machine? You can also launch a managed
  **[Kubernetes](/guides/kubernetes-access)** or **[Slurm](/guides/slurm-access)**
  cluster across your reserved GPU nodes from the Clusters page.
</Note>

## Prerequisites

Before you can configure an access mode for a reservation, the following must be true:

* The bid has been promoted to a confirmed reservation, and the reservation is visible in your portfolio.
* **Checkout and payment** for the reservation are complete. Access cannot be launched or changed on a reservation with outstanding payment.
* Your account has **at least one active SSH public key** registered. Add keys from the **SSH keys** tab on the Account page or with `ornn ssh-keys add`. See [Manage SSH keys](/guides/ssh-keys).

## Configure the access mode

<Steps>
  <Step title="Open the reservation detail page">
    From your Portfolio (`/portfolio`), click **View** on the reservation you want to configure. The
    detail page opens at `/portfolio/[reservationId]`. The legacy `/portfolio/access` URL redirects
    here.
  </Step>

  <Step title="Choose VM or Bare Metal">
    Pick the access mode you want from the access section. VM and Bare Metal cannot run
    simultaneously on the same reservation.
  </Step>

  <Step title="Add an SSH key and launch">
    In the **SSH Keys** section, click **Add Key** to add a key to the reservation, or confirm one
    is already there. Then launch. Ornn authorizes the reservation's active keys on the host.
  </Step>

  <Step title="Wait for the host to be ready">
    Provisioning takes a few minutes. The **SSH Host** and **User** fields (plus a ready-to-run
    **Quick Connect** command) appear in the Connect section of the reservation detail page once the
    host is ready.
  </Step>
</Steps>

<Note>
  The CLI's `ornn access` commands (`activate`, `show`, `push-keys`) cover **Bare Metal** only. `ornn access activate <reservation-id> --ssh-key-id <key-id>` performs the initial Bare Metal launch and installs the first key. VM access is configured and launched from the reservation detail page in the web app; there is no `ornn access` equivalent for VM.
</Note>

## Connecting over SSH

Once the host is ready, connect with your preferred SSH client:

```bash theme={null}
ssh <tenant-username>@<ssh-endpoint>
```

The values for these placeholders come from the **SSH Host** and **User** fields in the Connect section of the reservation detail page. From the CLI you can also fetch them on demand:

```bash theme={null}
ornn access show <reservation-id>
ornn access show <reservation-id> --json
```

### Save the connection in `~/.ssh/config`

For repeated access, add a Host entry to your local SSH config:

```bash theme={null}
Host ornn-h100
  HostName <ssh-endpoint>
  User <tenant-username>
  IdentityFile ~/.ssh/id_ed25519
  IdentitiesOnly yes
  ServerAliveInterval 60
```

Then connect with `ssh ornn-h100`.

### Port forwarding

Forward a local port to a service running on the host (for example, a Jupyter server on port 8888):

```bash theme={null}
ssh -L 8888:localhost:8888 <tenant-username>@<ssh-endpoint>
```

### Copying files

Move data on and off the host with `scp` or `rsync`:

```bash theme={null}
scp ./dataset.tar.gz <tenant-username>@<ssh-endpoint>:/data/
rsync -avh ./project/ <tenant-username>@<ssh-endpoint>:/home/<tenant-username>/project/
```

## After you connect

Verify the GPUs are visible to the host:

```bash theme={null}
nvidia-smi
```

You should see your allocated GPUs listed with driver and CUDA versions. If you're on the Ornn base image, PyTorch is already available:

```bash theme={null}
python -c "import torch; print(torch.cuda.is_available(), torch.cuda.device_count())"
```

## Adding more keys to a running reservation

If a teammate needs to connect to the same host, or if you want to rotate keys, push another registered key onto a launched reservation:

```bash theme={null}
ornn access push-keys <reservation-id> --ssh-key-id <key-id>
```

The newly pushed key is authorized alongside any keys already on the host.

## Switching access modes

You can switch between VM and Bare Metal on the same reservation, but it tears down the current environment.

<Warning>
  Switching access modes after launch tears down the existing environment. Anything stored on the
  previous mode that has not been persisted off the host will be lost. Copy out any data you need
  first.
</Warning>

To switch: open the reservation detail page, pick the other mode, make sure the reservation has an active SSH key, and launch.

## Data persistence

Ornn does not snapshot or back up data stored on the host. Treat the host as ephemeral within the reservation term:

* Persist datasets and checkpoints to your own object storage (S3, GCS, R2, etc.) regularly.
* Save before switching access modes; switching tears the environment down.
* At the end of the reservation term, the host is released and any data on it is no longer accessible.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Permission denied (publickey)">
    The SSH key you're connecting with isn't authorized on the host. Confirm the key you attached to the reservation matches the private key your SSH client is using:

    ```bash theme={null}
    ssh -i ~/.ssh/id_ed25519 -v <tenant-username>@<ssh-endpoint>
    ```

    To push a different registered key onto the host, run `ornn access push-keys <reservation-id> --ssh-key-id <key-id>`.
  </Accordion>

  <Accordion title="Connection refused or timed out">
    The host may still be provisioning. Check the reservation detail page. If the **SSH Host** field
    isn't visible yet, wait a few minutes and retry. If the host is shown but unreachable, verify your
    local network allows outbound SSH on the listed port.
  </Accordion>

  <Accordion title="Host key changed warning">
    If you reconnect after switching access modes or relaunching, the host key may change. Remove the old entry from `~/.ssh/known_hosts` and reconnect:

    ```bash theme={null}
    ssh-keygen -R <ssh-endpoint>
    ```
  </Accordion>

  <Accordion title="`nvidia-smi` shows no GPUs">
    On the Ornn base image this should never happen; file a support ticket. On a custom image or Bare
    Metal, confirm NVIDIA drivers are installed and loaded (`lsmod | grep nvidia`) and that the kernel
    matches the driver build.
  </Accordion>

  <Accordion title="The access section is grayed out">
    Access setup is gated on **completed checkout/payment** and **at least one registered SSH key**. Confirm both: check Account → Billing for outstanding invoices, and the SSH keys tab for at least one active key.
  </Accordion>
</AccordionGroup>

## Learn more

<CardGroup cols={2}>
  <Card title="VM access" img="https://mintcdn.com/ornn/fNQRwmmR9H-yzza5/images/banners/vm-access.jpg?fit=max&auto=format&n=fNQRwmmR9H-yzza5&q=85&s=11440154a7d2f11d5f64d61ac90c23c3" href="/guides/vm-access" width="1200" height="800" data-path="images/banners/vm-access.jpg">
    Launch a managed VM with the Ornn base image or an approved custom image.
  </Card>

  <Card title="Bare Metal access" img="https://mintcdn.com/ornn/fNQRwmmR9H-yzza5/images/banners/bare-metal-access.jpg?fit=max&auto=format&n=fNQRwmmR9H-yzza5&q=85&s=6276c46ea54e80732c14919ccb9661a1" href="/guides/bare-metal-access" width="1200" height="800" data-path="images/banners/bare-metal-access.jpg">
    SSH directly into the GPU host for maximum performance with no virtualization overhead.
  </Card>

  <Card title="Manage SSH keys" img="https://mintcdn.com/ornn/fNQRwmmR9H-yzza5/images/banners/ssh-keys.jpg?fit=max&auto=format&n=fNQRwmmR9H-yzza5&q=85&s=f17bae5a05d5d6981e1cc7e88d4e664f" href="/guides/ssh-keys" width="1200" height="800" data-path="images/banners/ssh-keys.jpg">
    Register the public key you'll attach to a reservation before launch.
  </Card>

  <Card title="Completing checkout" img="https://mintcdn.com/ornn/fNQRwmmR9H-yzza5/images/banners/checkout.jpg?fit=max&auto=format&n=fNQRwmmR9H-yzza5&q=85&s=34b04e114a261e5e8b4c426cf19ac64f" href="/guides/checkout" width="1200" height="800" data-path="images/banners/checkout.jpg">
    Finish payment so access mode changes are unlocked for your reservation.
  </Card>
</CardGroup>