Skip to content

One-click apps

A one-click app installs and starts an application on a GPU instance's first boot, so it is running a few minutes after the instance comes up. Pick Jupyter Lab, a vLLM or SGLang server, Ollama with Open WebUI, ComfyUI or a PyTorch dev box when you deploy, and skip the setup. This page covers each app, how to reach it, how to find a GPU with enough memory for a model, and the API.

Available apps

AppWhat it runsWhere you reach itSign-inSetup time
Jupyter Lab with PyTorchNotebooks with PyTorch built for the GPUPublic IP, port 8888TokenAbout 5 minutes
vLLM serverAn OpenAI-compatible API for a Hugging Face model, across every GPU on the machinePublic IP, port 8000API keyAbout 10 minutes
SGLang serverAn OpenAI-compatible API for a Hugging Face model, an alternative to vLLMPublic IP, port 30000API keyAbout 12 minutes
Ollama with Open WebUIA chat app in your browser, with Ollama running the model on the GPUOpen WebUI: public IP, port 8080. Ollama API: SSH tunnel, port 11434Password for Open WebUIAbout 8 minutes
ComfyUINode-based image and video generationSSH tunnel, port 8188None, SSH onlyAbout 6 minutes
PyTorch dev boxPyTorch with Transformers, Datasets and Accelerate, plus tmux, htop and nvtopSSHYour SSH keyAbout 5 minutes

Setup time counts from boot. A large model adds its download time on first start.

Apps with their own sign-in listen on the instance's public IP, behind a token, API key or password made for that instance. ComfyUI and the Ollama API have no sign-in, so they listen on the instance only and you reach them through an SSH tunnel.

Requirements

  • A virtual machine. Containers do not run startup scripts. For a container, start from a container template instead.
  • An offer that takes a startup script. Apps install through the startup script, so the offer's supportsCloudInit must be true. That covers Spheron ES, Spheron MS, Verda, and the Spheron AI provider machines that take a startup script.
  • An NVIDIA GPU. The apps install CUDA builds. They are not offered on AMD GPUs (Spheron AM) or Intel Gaudi. For AMD, see ROCm on AMD GPUs.
  • Open ports. With a firewall set to Only these ports, keep the app's port open, and TCP 22 for an app reached over an SSH tunnel.

The One-click app card shows only on offers where an app can run.

Deploy an app from the dashboard

Pick an offer

Open Deploy GPUs, pick a GPU and region, and choose Next.

Choose the app

On the SSH Key step, choose an app in the One-click app card. Each app shows its ports and its setup time.

Name the model (optional)

For vLLM and SGLang, type a Hugging Face model id, for example Qwen/Qwen3-32B. For Ollama with Open WebUI, type an Ollama model name, for example qwen2.5:7b. Leave it empty for the default: Qwen/Qwen2.5-1.5B-Instruct for vLLM and SGLang, llama3.2 for Ollama.

Make sure the model fits the machine's GPU memory. See Find offers that fit a model. For a gated model such as Llama, see Use a gated Hugging Face model.

Deploy

Add your own startup script below the card if you need one. It still runs: the app's setup starts first and continues in the background. Choose Deploy Instance.

A sign-in secret is made for each instance. It shows on the instance page once the instance is running.

Use a gated Hugging Face model

As you type a Hugging Face model id, Deploy checks it with Hugging Face. A spinner shows at the end of the field while it checks.

  • Public model: nothing more to do.
  • Gated model, such as Llama or Gemma: accept the model's terms on its Hugging Face page, then paste a token from that account in the Hugging Face token field. A token with read access is enough.
  • Not found: check the name. For a private model, add a token from an account that can read it.

Deploy checks the token too. It tells you when Hugging Face does not accept the token, or when the account has not been given access to the model yet, and holds the deploy until the token works. The token goes to the instance only, as HF_TOKEN in /etc/spheron/app.env, and is never stored.

Follow the setup

Setup starts after the instance boots and takes the minutes shown in the table. To watch it, connect over SSH and follow the log:

# Every line of the install, ending with "setup finished"
sudo tail -f /var/log/spheron-app.log

Open the app

Open Instances and choose the instance. Its connection panel shows the app's name, each port's address or SSH tunnel command, and the sign-in secret behind Show and Copy.

Jupyter Lab

Open http://<ip-address>:8888/lab and sign in with the token. Notebooks live in the login user's home folder.

vLLM and SGLang

Call the OpenAI-compatible API with the API key as a bearer token. vLLM answers on port 8000 and SGLang on port 30000. Every route needs the key except health checks, so nobody who finds the address can send requests:

# List the model the server is serving
curl http://<ip-address>:8000/v1/models \
  -H "Authorization: Bearer <api-key>"
 
# Send a chat request
curl http://<ip-address>:8000/v1/chat/completions \
  -H "Authorization: Bearer <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Qwen/Qwen2.5-1.5B-Instruct",
    "messages": [{ "role": "user", "content": "Hello" }]
  }'

The model downloads on first start, so a large one takes a while before the API answers. On SGLang, the first request after a start can take a minute or two while kernels compile.

Ollama with Open WebUI

Open http://<ip-address>:8080 and sign in as admin@example.com with the password from the instance page. Sign-ups are closed, so nobody who finds the address can register. Setup checks both before it opens port 8080: if the admin account cannot sign in or a sign-up is not refused, Open WebUI stays off and the setup log says why.

The Ollama API listens on the instance only. Reach it through an SSH tunnel, or pull more models over SSH:

# On the instance: add another model
ollama pull qwen2.5:7b

ComfyUI

ComfyUI has no sign-in, so it listens on the instance only. Open the tunnel with the command from the instance page, then browse to http://localhost:8188:

# Keep this running while you use ComfyUI
ssh -N -L 8188:localhost:8188 <user>@<ip-address>

Put checkpoints in ~/ComfyUI/models/checkpoints.

PyTorch dev box

Connect over SSH. The Python environment is active in every new shell, with PyTorch built for the GPU.

Manage the app

Each app runs as a systemd service as the login user, so it comes back after a reboot or a Stop and Start.

AppService
Jupyter Labspheron-jupyter
vLLM serverspheron-vllm
SGLang serverspheron-sglang
Ollama with Open WebUIollama and spheron-open-webui
ComfyUIspheron-comfyui
# Check the service and read its output
sudo systemctl status spheron-vllm
sudo journalctl -u spheron-vllm -f

The app's settings live in /etc/spheron/app.env, and its Python environment in /opt/spheron/app/venv.

Serve a different model, or change the token

To serve another model, change the MODEL= line in /etc/spheron/app.env and restart the service. To add or change the Hugging Face token later, set the HF_TOKEN= line in the same file:

sudo nano /etc/spheron/app.env
sudo systemctl restart spheron-vllm

Install for your GPU's driver

Each app installs the builds that match the instance's NVIDIA driver. A CUDA 13 driver gets the newest vLLM and SGLang. A CUDA 12 driver gets the last builds made for CUDA 12: vLLM 0.32.0 and SGLang 0.5.10.

Find offers that fit a model

On Deploy GPUs, Fits a model in the offer toolbar, next to the provider and region filters, lists popular open models, from Llama 3.1 8B to Kimi K3, with each maker's logo and the GPU memory each needs. Search the list by name, pick one, and each GPU card keeps only the offers with enough total GPU memory to serve it. It works before you sign in too.

Each model starts at the precision it is published in. Choose FP16, FP8 or INT4 at the bottom of the list to see the memory each needs.

The memory needed is:

ceil(parameters in billions x bytes per parameter x 1.2) GB

with 2 bytes for FP16, 1 for FP8 and 0.5 for INT4. The extra 20% leaves room for the KV cache and runtime at a modest context length. An offer fits when its GPU memory per GPU times its GPU count reaches that figure.

Through the API, send fitsModel and an optional precision to GET /api/gpu-offers. For a model not in the list, send minVramGb instead:

# Offers that can serve Llama 3.3 70B at FP8
curl "https://app.spheron.ai/api/gpu-offers?fitsModel=llama-3.3-70b&precision=fp8"
 
# Offers with at least 48 GB of GPU memory in total
curl "https://app.spheron.ai/api/gpu-offers?minVramGb=48"

GET /api/app-recipes lists every model id with the memory it needs at each precision.

Use the API

List the apps, then deploy with recipe. Send an app id, or { "id", "model" } to choose the model:

# The apps, their ports, and the models fitsModel knows. No API key needed.
curl https://app.spheron.ai/api/app-recipes
 
# Deploy a vLLM server for Qwen3 32B
curl -X POST https://app.spheron.ai/api/deployments \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "spheron-ai",
    "offerId": "<offer-id>",
    "gpuType": "<gpu-type>",
    "gpuCount": 1,
    "region": "<region>",
    "operatingSystem": "<os-option>",
    "instanceType": "DEDICATED",
    "sshKeyId": "<your-ssh-key-id>",
    "recipe": { "id": "vllm", "model": "Qwen/Qwen3-32B" }
  }'

App ids are jupyter, vllm, sglang, ollama-webui, comfyui and pytorch. For a gated or private Hugging Face model on vllm or sglang, add "hfToken": "hf_..." to recipe. It is written to the instance as HF_TOKEN and never stored or returned.

GET /api/deployments/{deploymentId} then carries recipe: the app, its ports and how to use it, and once the instance is running, each port's url or sshTunnelCommand. Read the sign-in secret with GET /api/deployments/{deploymentId}/access-token. See the API reference for every field.

A request with recipe returns 400 validation_error on a container, on an offer whose supportsCloudInit is false, on an AMD or Intel GPU, and when a restricted firewall closes the app's ports. For vllm and sglang it also returns 400 when Hugging Face says the model does not exist, or is gated and hfToken is missing, not accepted, or from an account without access. When Hugging Face cannot be reached, the deploy goes ahead.

Use apps with AI connections

Assistants connected through AI connections can list the apps, find offers that fit a model, deploy an instance with an app, and read its addresses. For a gated model, they can pass your Hugging Face token as recipe.hfToken. They never see the sign-in secret, which shows only on your dashboard.

What's next

  • Startup script: Run your own setup on first boot, alongside an app
  • Firewall: Choose which ports accept incoming connections
  • Networking: Public IPs and SSH tunneling
  • vLLM: Serve models with vLLM by hand, with every option
  • API reference: The app and model endpoints

Troubleshooting

Issue: The One-click app card is missing

Symptoms: No One-click app card on the SSH Key step.

Diagnosis: The offer is a container, takes no startup script, or has an AMD or Intel GPU.

Resolution: Pick a virtual machine offer with an NVIDIA GPU on a provider that runs startup scripts.

Issue: The app's address does not answer

Symptoms: The address times out or refuses the connection after the instance is running.

Diagnosis: Setup is still running, or a firewall rule closes the port.

Resolution: Follow sudo tail -f /var/log/spheron-app.log until it shows setup finished. Check the instance's firewall keeps the app's port open.

Issue: The deploy is refused because of the firewall

Symptoms: Deploy fails with "... which your firewall closes".

Diagnosis: The firewall is set to Only these ports and leaves out the app's port, or TCP 22 for an app reached over an SSH tunnel.

Resolution: Add a TCP rule for the port named in the message, or keep All ports open.

Issue: vLLM or SGLang keeps restarting

Symptoms: systemctl status spheron-vllm shows the service restarting, and the API never answers.

Diagnosis: The model does not fit the GPU memory, or its Hugging Face token is missing or cannot read it.

Resolution: Read sudo journalctl -u spheron-vllm -n 100. Pick a smaller model or a bigger offer, or set HF_TOKEN in /etc/spheron/app.env and restart the service.