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
| App | What it runs | Where you reach it | Sign-in | Setup time |
|---|---|---|---|---|
| Jupyter Lab with PyTorch | Notebooks with PyTorch built for the GPU | Public IP, port 8888 | Token | About 5 minutes |
| vLLM server | An OpenAI-compatible API for a Hugging Face model, across every GPU on the machine | Public IP, port 8000 | API key | About 10 minutes |
| SGLang server | An OpenAI-compatible API for a Hugging Face model, an alternative to vLLM | Public IP, port 30000 | API key | About 12 minutes |
| Ollama with Open WebUI | A chat app in your browser, with Ollama running the model on the GPU | Open WebUI: public IP, port 8080. Ollama API: SSH tunnel, port 11434 | Password for Open WebUI | About 8 minutes |
| ComfyUI | Node-based image and video generation | SSH tunnel, port 8188 | None, SSH only | About 6 minutes |
| PyTorch dev box | PyTorch with Transformers, Datasets and Accelerate, plus tmux, htop and nvtop | SSH | Your SSH key | About 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
supportsCloudInitmust 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.logOpen 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:7bComfyUI
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.
| App | Service |
|---|---|
| Jupyter Lab | spheron-jupyter |
| vLLM server | spheron-vllm |
| SGLang server | spheron-sglang |
| Ollama with Open WebUI | ollama and spheron-open-webui |
| ComfyUI | spheron-comfyui |
# Check the service and read its output
sudo systemctl status spheron-vllm
sudo journalctl -u spheron-vllm -fThe 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-vllmInstall 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) GBwith 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.