Quick Start: Ubuntu with SSH

The fastest way to get a GPU-enabled machine is using a Job Recipe in the Console. This guide walks you through launching an Ubuntu instance with SSH access.

What You’ll Need

• An SSH key pair (public and private keys)

Don’t have SSH keys? Generate a dedicated key pair for Dispersed:

ssh-keygen -t ed25519 -f ~/.ssh/dispersed -C "[e-mail]"

This creates a separate key pair that won’t affect any of your existing SSH keys. Your public key is at ~/.ssh/dispersed.pub.

---

What is a Job Recipe?

A Job Recipe is a pre-configured template that simplifies Job creation. Instead of specifying hardware requirements and Docker configuration manually, you select a recipe and fill in a few inputs.

The ubuntu:24.04 recipe provides:

• Ubuntu 24.04 base image
• SSH server pre-configured
• 4GB RAM, 10GB storage by default

---

Launch Your Instance

Step 1: Select Recipe

1. Sign in to the Dispersed Console
2. Go to Run in the sidebar
3. In the Recipe section, find ubuntu:24.04 and click to select
4. In the GPU section, choose Any compatible GPU

Step 2: Fill in Inputs

In the configuration modal, provide the required inputs:

Input	Description	Example
SSH Public Key	Your SSH public key	ssh-ed25519 AAAA... user@host
Allowed IPs	IP addresses allowed to connect	0.0.0.0/0 (any)

Step 3: Submit

Click Submit Job. You’ll be redirected to the Job Detail page.

Step 4: Wait for Node Assignment

After submitting, your Job goes through these stages:

Status	Description
PENDING	The network is searching for a Node with your specs
ASSIGNED	A Node has been selected and is preparing your container
RUNNING	Your container is running and ready for connections

Once a Node is assigned, a Job Run is automatically created. This may take a few seconds to a few minutes depending on network availability.

Step 5: Get Connection Info

When your Job shows RUNNING:

1. On the Job Detail page, find the Job Runs section
2. Click on the Job Run to open the Job Run Detail page
3. The connection information appears under Node URLs

You’ll see the hostname and port needed for SSH access.

Step 6: Connect

Use the connection info from the Job Run Detail page:

ssh -i ~/.ssh/dispersed -p <port> duser@<hostname>

The Job Run page updates automatically as status changes. Refresh if needed to see the latest connection information.

---

Stopping Your Job

The Ubuntu with SSH recipe creates a PERSISTENT job that runs until you stop it. Remember to stop your job when finished to avoid continued billing.

1. Navigate to Jobs in the Console
2. Click on your Job to view details
3. Click Stop (for running jobs) or Cancel (for pending jobs)

---

Forking Recipes

Want to customize an official recipe? Fork it to create your own version with modified settings.

How to Fork

1. Navigate to Recipes in the Console
2. Click on a recipe to view its details
3. Click the Fork button
4. Enter a name and optional description for your fork
5. Click Fork Recipe to create your copy

Your forked recipe appears in the My Recipes tab and can be launched just like official recipes. You can then edit your fork to customize hardware requirements, Docker image, or default inputs.

Fork a recipe when you need different hardware specs, a custom Docker image, or want to pre-fill inputs you use repeatedly. Your fork stays independent — updates to the original recipe won’t affect your version.

---

Troubleshooting

Issue	Solution
Connection refused	Wait for Job Run status to be RUNNING, verify allowed_ips
Permission denied (publickey)	Verify SSH key matches what you submitted
Job stuck in PENDING	No Nodes available with required specs — try again later
No Job Run appears	Wait for a Node to be assigned — Job Run is created on assignment

---

Using the API

For programmatic access to Job Recipes, you’ll need an API Key and HMAC signature authentication. See Authenticate Requests for implementation details and code examples.