---
title: "ACE-Step 1.5 — Local Network Setup Guide"
description: "How to run ACE-Step AI music generator on the local network via Gradio UI or REST API, including .env configuration and startup notes."
type: guide
domain: development
tags: [ace-step, ai, music-generation, gradio, gpu, cuda]
---

# ACE-Step 1.5 — Local Network Setup

ACE-Step is an open-source AI music generation model. This guide covers running it on the workstation and serving the Gradio web UI to the local network.

## Location

```
/mnt/NV2/Development/ACE-Step-1.5/
```

Cloned from GitHub. Uses `uv` for dependency management — the `.venv` is created automatically on first run.

## Quick Start (Gradio UI)

```bash
cd /mnt/NV2/Development/ACE-Step-1.5
./start_gradio_ui.sh
```

Accessible from any device on the network at **http://10.10.0.41:7860** (or whatever the workstation IP is).

## .env Configuration

The `.env` file in the project root persists settings across git updates. Current config:

```env
SERVER_NAME=0.0.0.0
PORT=7860
LANGUAGE=en
```

### Key Settings

| Variable | Default | Description |
|----------|---------|-------------|
| `SERVER_NAME` | `127.0.0.1` | Set to `0.0.0.0` for LAN access |
| `PORT` | `7860` | Gradio UI port |
| `LANGUAGE` | `en` | UI language (`en`, `zh`, `he`, `ja`). **Must be set** — empty value causes `unbound variable` error with the launcher's `set -u` |
| `ACESTEP_CONFIG_PATH` | `acestep-v15-turbo` | DiT model variant |
| `ACESTEP_LM_MODEL_PATH` | `acestep-5Hz-lm-0.6B` | Language model for lyrics/prompts |
| `ACESTEP_INIT_LLM` | `auto` | `auto` / `true` / `false` — auto detects based on VRAM |
| `CHECK_UPDATE` | `true` | Set to `false` to skip interactive update prompt (useful for background/automated starts) |

See `.env.example` for the full list.

## REST API Server (Alternative)

For programmatic access instead of the web UI:

```bash
cd /mnt/NV2/Development/ACE-Step-1.5
./start_api_server.sh
```

Default: `http://127.0.0.1:8001`. To serve on LAN, edit `start_api_server.sh` line 12:

```bash
HOST="0.0.0.0"
```

API docs available at `http://<ip>:8001/docs`.

## Hardware Profile (Workstation)

- **GPU**: NVIDIA RTX 4080 SUPER (16 GB VRAM)
- **Tier**: 16GB class — auto-enables CPU offload, INT8 quantization, LLM
- **Max batch (with LM)**: 4
- **Max batch (without LM)**: 8
- **Max duration (with LM)**: 480s (8 min)
- **Max duration (without LM)**: 600s (10 min)

## Startup Behavior

1. Loads `.env` configuration
2. Checks for git updates (interactive prompt — set `CHECK_UPDATE=false` to skip)
3. Creates `.venv` via `uv sync` if missing (slow on first run)
4. Runs legacy NVIDIA torch compatibility check
5. Loads DiT model → quantizes to INT8 → loads LM → allocates KV cache
6. Launches Gradio with queue for multi-user support

Full startup takes ~30-40 seconds after first run.

## Gotchas

- **LANGUAGE must be set in `.env`**: The system `$LANGUAGE` locale variable can be empty, causing the launcher to crash with `unbound variable` due to `set -u`. Always include `LANGUAGE=en` in `.env`.
- **Update prompt blocks background execution**: If running headlessly or from a script, set `CHECK_UPDATE=false` to avoid the interactive Y/N prompt.
- **Model downloads**: First run downloads ~4-5 GB of model weights from HuggingFace. Subsequent runs use cached checkpoints in `./checkpoints/`.