How do I run ACE-Step 1.5 on a cloud GPU?

Cover: Run ACE-Step 1.5 on a cloud GPU, music generation step by step

Deploy a Raw GPU, check the driver with nvidia-smi, clone the ACE-Step 1.5 repository, run uv sync, then start the Gradio UI with uv run acestep --server-name 127.0.0.1 --port 7860 and open it on your computer through an SSH tunnel; according to the official ACE-Step installation guide, it needs Python 3.11 to 3.12 and downloads its models automatically on first run.

Updated 2026-11-01

This guide follows the official ACE-Step 1.5 README, installation guide, GPU troubleshooting page and REST API doc, plus the Ace-Step1.5 model card, all read on 2026-11-01. ACE-Step 1.5 is a music generation model that writes full songs from a text description and optional lyrics. This guide is for people who want to run it on a rented NVIDIA GPU such as the RTX 5090 or the other cards listed on /pricing.

Before you use a base model, check the licence on its official model page: Ace-Step1.5. The README also encourages users to verify the originality of generated works and to clearly disclose AI involvement.

Step 1: Deploy a Raw GPU and connect

On /deploy, pick an NVIDIA GPU and the Raw GPU option (JupyterLab + CUDA pre-installed, root SSH). Connect over SSH or open a terminal in JupyterLab.

VRAM need depends on model, precision and workflow; see the official figures in Step 5 and How much VRAM do I need to run an LLM? for how model size and precision add up.

Step 2: Check the environment first

nvidia-smi          # GPU name, driver version and the "CUDA Version" the driver supports
nvcc --version      # CUDA toolkit compiler, if installed
python3 --version   # the ACE-Step docs ask for a stable Python 3.11 or 3.12
git --version

What to look for:

  • Driver and CUDA Version. The ACE-Step GPU troubleshooting page says “The CUDA version in your PyTorch build must be compatible with your driver”. On Linux x86_64, the project’s pyproject.toml pins PyTorch 2.10.0 built for CUDA 12.8 (torch==2.10.0+cu128). After Step 3 you can compare the two with the commands in Step 7.
  • Python version. The installation guide warns that some Linux distributions ship Python 3.11.0rc1, a pre-release that “can cause segmentation faults with the vLLM backend”, and suggests a stable release (3.11.12 or newer). uv can download a stable Python for the project, so the system Python matters less if you use the uv path below.

Step 3: Install uv and ACE-Step 1.5

According to the official ACE-Step installation guide, install uv, clone the repository and sync its dependencies:

curl -LsSf https://astral.sh/uv/install.sh | sh
source ~/.local/bin/env            # if `uv` is not found yet; or open a new shell

git clone https://github.com/ACE-Step/ACE-Step-1.5.git
cd ACE-Step-1.5
uv sync

uv sync creates a .venv in the project folder and installs the pinned PyTorch build and the other dependencies.

Step 4: Download the models (optional)

The installation guide says “Models are downloaded automatically on first run” from Hugging Face. To fetch them before you start the UI, use the project’s downloader:

uv run acestep-download                    # main model: VAE, text encoder, acestep-v15-turbo DiT, acestep-5Hz-lm-1.7B
uv run acestep-download --list             # list every available model

According to the README, ACE-Step 1.5 XL uses “a 4B-parameter DiT decoder for higher audio quality”, in three variants: xl-base, xl-sft and xl-turbo. The installation guide’s manual download line for acestep-v15-xl-turbo is:

huggingface-cli download ACE-Step/acestep-v15-xl-turbo --local-dir ./checkpoints/acestep-v15-xl-turbo

The Hugging Face repos for these models are not gated, so no access request is needed. For more on download flags and caching, see How do I download a Hugging Face model on a cloud GPU?.

Step 5: Choose a model (official VRAM figures)

These are the ACE-Step project’s own figures, quoted from its README and installation guide (read 2026-11-01). They are not CloudGPU measurements.

  • “≥4GB for DiT-only mode; ≥6GB for LLM+DiT” (installation guide, Requirements).
  • XL (4B) DiT models: “They require ≥12GB VRAM (with offload + quantization) or ≥20GB (without offload)” (README, Model Zoo).
  • --offload_to_cpu is “auto-enabled if VRAM < 20GB” (installation guide, Command Line Options).

According to the README, the UI picks a configuration for the detected GPU tier on its own, covering the language model, backend, offloading and quantization (“tier-aware and pre-configured”). To choose yourself, set the models in a .env file in the project folder (the README’s example):

cp .env.example .env
# then edit .env, for example:
# ACESTEP_CONFIG_PATH=acestep-v15-turbo
# ACESTEP_LM_MODEL_PATH=acestep-5Hz-lm-1.7B

Step 6: Start the Gradio UI and open it through an SSH tunnel

uv run acestep --server-name 127.0.0.1 --port 7860

The installation guide lists 127.0.0.1 as the default server address and 7860 as the default port. Keeping it on 127.0.0.1 means the UI is only reachable through your tunnel. On your own computer, open a tunnel with the SSH host and port shown for your instance:

ssh -N -L 7860:127.0.0.1:7860 <user>@<instance-host> -p <ssh-port>

Then open http://localhost:7860 in your browser. See How do I use SSH port forwarding on a cloud GPU? for details. The SSH tunnel is the only way this guide opens the UI.

To keep the server running after you close the SSH session, run it inside tmux or screen.

Optional: the REST API server

export ACESTEP_API_KEY=your-secret-key
uv run acestep-api

According to the ACE-Step REST API doc, the API listens on http://localhost:8001, and with a key set, every request needs Authorization: Bearer your-secret-key (or ai_token in the body). Tunnel port 8001 the same way as 7860. The API doc lists the task endpoints, such as /release_task and /query_result.

Step 7: Troubleshooting

According to the official ACE-Step docs:

  • No GPU detected. Run nvidia-smi. Then compare the CUDA version of the installed PyTorch with the driver:

    uv run python -c "import torch; print(torch.version.cuda, torch.cuda.is_available())"
nvidia-smi   # "CUDA Version: X.X" in the header

    The PyTorch build must be compatible with the driver.

  • Crashes with the vLLM backend. If you are stuck on a pre-release Python and cannot upgrade, the installation guide suggests the PyTorch backend: uv run acestep --backend pt. The troubleshooting page adds that GPUs with compute capability below 7.0 are switched to the pt backend automatically; check yours with uv run python -c "import torch; print(torch.cuda.get_device_capability())".

  • Out of memory. Use a smaller model from Step 5, disable the language model with ACESTEP_INIT_LLM=false (DiT-only mode), or let CPU offload stay on.

Step 8: Download your songs and destroy the instance

Generated audio stays on the instance. Download the files you want to keep before you destroy it. Billed per minute, rounded up, with a 1-minute minimum; billing stops when you destroy the instance. See /terms.

FAQ

What does ACE-Step 1.5 need on a cloud GPU?

According to the official ACE-Step installation guide, it needs Python 3.11 to 3.12 (a stable release), and a CUDA GPU is recommended. On Linux x86_64 the project pins PyTorch 2.10.0 built for CUDA 12.8, so check with nvidia-smi that the driver is compatible with that build.

How much VRAM does ACE-Step 1.5 need?

The ACE-Step installation guide lists 4GB or more for DiT-only mode and 6GB or more for LLM plus DiT. The README says the XL (4B) DiT models need 12GB or more with offload and quantization, or 20GB or more without offload. These are the project’s own figures, not CloudGPU measurements.

Which port does the ACE-Step UI use?

The Gradio UI defaults to port 7860 on 127.0.0.1, and the REST API server uses port 8001. Reach either one from your computer through an SSH tunnel.

Can I use ACE-Step 1.5 commercially?

Before you use a base model, check the licence on its official model page: https://huggingface.co/ACE-Step/Ace-Step1.5. The README also encourages users to verify the originality of generated works and to clearly disclose AI involvement.

How is a Raw GPU billed while ACE-Step runs?

Billed per minute, rounded up, with a 1-minute minimum; billing stops when you destroy the instance. See https://cloudgpu.app/terms for the full terms.