Quick Start

This guide will walk through going from zero to SSHing into an instance using the CLI. You can also do this using the web console.

Logging In

The first thing we’ll need to do, is login to an Oxide control plane.

$ oxide auth login --host https://engineering.cloud.example.com

Opened this URL in your browser:
  https://engineering.cloud.example.com/device/verify

Enter the code: CXKX-KPBK
Note
Here we use the fictitious control plane URL https://engineering.cloud.example.com you’ll need to replace this with the URL of your Oxide control plane.

When the browser window pops up, enter the code displayed on the command line and your CLI should be logged in! If you are not using a computer with a GUI and web browser you can supply the --no-browser option and go to the URL provided by the CLI manually on another machine.

Creating a Project

Creating a project from the CLI is a one-liner.

$ oxide project create --name prototypes --description "experimental work"

Upload an Image

To launch an instance, we need to add an image to our new project. The Oxide platform runs cloud-init-based images in raw image format. Let’s download one to get started. You can skip this step if you already have your own image.

$ curl -OL https://cloud.debian.org/images/cloud/bookworm/latest/debian-12-genericcloud-amd64.raw

Now let’s upload this image to the Oxide control plane.

$ oxide disk import \
    --path debian-12-genericcloud-amd64.raw \
    --disk bookworm-boot \
    --project prototypes \
    --description "Debian bookworm disk" \
    --snapshot bookworm-snapshot \
    --image bookworm \
    --image-description "Debian bookworm image" \
    --image-os Debian \
    --image-version 12

That’s it! On to the final step of creating an instance.

Upload an SSH Key

To access our instances via SSH we’ll need to upload a key prior to launching them. If you don’t have a SSH key pair for use on Oxide yet, you can follow the instructions here to generate a new one.

$ oxide current-user ssh-key create \
    --name personal \
    --description "My personal ssh key" \
    --public-key "$(cat $HOME/.ssh/cloud_rsa.pub)"
Note
Replace $HOME/.ssh/cloud_rsa.pub with your own public key file.

Create an Instance

Now we’ll create an instance using the image we just uploaded.

$ oxide instance from-image \
     --image bookworm \
     --name pegasus \
     --project prototypes \
     --description "Phasing cloaking device" \
     --hostname pegasus \
     --memory 16g \
     --ncpus 8 \
     --size 200g \
     --start

Once this command returns, we should be able to ask about the external IP address assigned to the instance.

$ oxide instance external-ip list --project prototypes --instance pegasus
success
ExternalIpResultsPage {
    items: [
        Ephemeral {
            ip: 172.20.26.52,
        },
    ],
    next_page: None,
}

We can use that information to ssh into the machine 🎉.

Note
Depending on the cloud image being used, it may take a minute or two for SSH to become available.
$ ssh debian@172.20.26.52
Linux pegasus 6.1.0-10-cloud-amd64 #1 SMP PREEMPT_DYNAMIC Debian 6.1.38-2 (2023-07-27) x86_64

The programs included with the Debian GNU/Linux system are free software;
the exact distribution terms for each program are described in the
individual files in /usr/share/doc/*/copyright.

Debian GNU/Linux comes with ABSOLUTELY NO WARRANTY, to the extent
permitted by applicable law.

debian@pegasus:~$
Last updated