Home / Installation

From repository to your studio.

A short setup. A local engine. Start with your machine, then let UnstableField handle the technical choices.

Before you begin

Three things to have ready.

Check these before running the installer. Hardware determines which generation tasks and models are eligible.

A supported machine

Check VRAM and RAM against the hardware guide. CPU-only use is chat-only.

Hardware compatibility ↗

uv and node on PATH

Install both tools and make them available in your terminal before starting.

Installation prerequisites ↗

A GitHub checkout

Get the repository from GitHub and open a terminal in its checked-out directory.

View on GitHub ↗

The recommended path

Install. Launch. Make it yours.

Run these commands from the checked-out repository. No separate end-user UI build commands are needed.

01
Run the installer
The installer probes your torch backend, syncs the matching extra, attempts sageattention on a best-effort basis, builds the UI and installs the launcher.
02
Open your local studio
Run unstablefield. The launcher starts the local web UI; the default address is 127.0.0.1 on port 7860.
03
Complete first setup
On first start, setup labels your machine and offers a model pack for each task. Choose an eligible pack before creating.

Terminal · repository directory

./install.shunstablefield

Your first model download

Model files need network access and local storage. First chat also downloads chat runtime libraries. Your content does not leave the machine for generation.

Model packs and licenses ↗

Advanced · optional

Choose a backend explicitly.

The installer handles this for most users. For manual engine setup, run one matching command from the engine directory.

NVIDIA · CUDA 13uv sync --extra cu130
NVIDIA · CUDA 13
engine directory
```
uv sync --extra cu130
```
AMD · ROCm 7.2uv sync --extra rocm
AMD · ROCm 7.2
engine directory
```
uv sync --extra rocm
```
Intel Arcuv sync --extra xpu
Intel Arc
engine directory
```
uv sync --extra xpu
```
Apple Siliconuv sync --extra mps
Apple Silicon
engine directory
```
uv sync --extra mps
```
Other · CPUuv sync --extra cpu
Other · CPU
engine directory
```
uv sync --extra cpu
```

Plain uv sync installs no torch. A bare uv run re-syncs without one: always pass the backend extra when invoking uv directly. Choosing a backend is not a guarantee that every model or task fits.

Your local environment

A launcher that stays out of your way.

Keep the defaults, or choose how the studio starts and where its data lives.

Useful launch options

--no-browser · Don’t open a browser automatically.

--port N · Choose a port; default 7860.

--host ADDR · Choose an address; default 127.0.0.1.

Alternative Python entry point

python -m unstablefield

Local data, in one place

Default data directory

~/.local/share/unstablefield/

UNSTABLEFIELD_DATA_DIR

This environment variable overrides the default. Logs and metrics stay local; Hugging Face telemetry is off.

A few useful answers

Before your first launch.

The details that matter when setting up a local engine.

Why does uv need a backend extra?

Plain uv sync installs no torch. A bare uv run re-syncs without a backend extra, too. Always pass the matching backend extra when using uv directly. The installer selects one for you.

Can I choose a different data directory?

Yes. UNSTABLEFIELD_DATA_DIR overrides the default local data location. Set it in your launch environment to choose where UnstableField keeps its data.

Will setup need an internet connection?

Yes. Model files are downloaded, and chat runtime libraries are downloaded on first chat. Generation itself runs on your machine; local generation is not a network-free installation.

← Hardware compatibility Browse the documentation ↗View on GitHub ↗