# Install / ติดตั้ง

On the server (a small VPS with a domain and HTTPS), create the config and an agent token, then on each
GPU machine run the one-liner that the server prints:

```
curl -fsSL https://YOUR-SERVER/get | WXCH_TOKEN=<agent token> sh
```

It asks for `sudo` once, installs the agent, Ollama, LM Studio and vLLM, downloads the smallest model of each
and runs a self-test. Safe to run again. `sh -s -- --dry-run` shows the plan without changing anything;
`sh -s -- uninstall` removes it (models are kept; `--all` removes them too).

## Support tiers

| Tier | Machines | Status |
|------|----------|--------|
| 1 | NVIDIA DGX Spark / GB10 "PGX" (DGX OS, arm64, unified memory) | verified on real hardware |
| 1 | Other DGX / Ubuntu with discrete NVIDIA GPUs (amd64 or arm64) | GPU memory (VRAM) is used for admission; installer tested in containers |
| 2 | Debian, Fedora, RHEL/Rocky/Alma, openSUSE, Arch (systemd) | installer tested in containers (CI matrix); Ollama + LM Studio; vLLM when Docker + NVIDIA GPU are present |
| 3 | Linux without systemd (Alpine, Void, ...) | the installer stops with a clear message; run `wxch-agent` by hand |

Machines without an NVIDIA GPU or without Docker skip vLLM automatically (set `WXCH_VLLM=required` to make that an error).
Ollama and LM Studio run on CPU there.

## Linux without systemd

Download the agent for your CPU from `https://YOUR-SERVER/dl/wxch-agent-amd64` (or `-arm64`), then run
`WXCH_TOKEN=<token> ./wxch-agent -server wss://YOUR-SERVER/ws/agent` under your own supervisor (runit, OpenRC, ...).

## Optional AI modules (image, video, speech) / โมดูล AI (ภาพ วิดีโอ เสียง)

A provider decides whether a machine offers these. **Nothing is installed by default.** Five capabilities:
`image.generate`, `image.edit`, `video.generate`, `video.edit`, `audio.transcribe` (all five: about 110 GB, of which the
engine image alone is 38.5 GB; each one's size is shown before you choose). Pick them in any of three ways:

```sh
# 1. in the full install (the modules step runs after the starter models)
curl -fsSL https://YOUR-SERVER/get | WXCH_TOKEN=<token> WXCH_MODULES=image.generate,audio.transcribe sh     # or WXCH_MODULES=all
# 2. later, on a machine that is already installed (updates the runner, then installs; no token needed)
curl -fsSL https://YOUR-SERVER/get | sh -s -- modules image.generate video.generate                          # or: modules all
# 3. from the control page: "AI modules" (tick, see the disk total, install; also remove)
```

The engines run directly on the machine, as child processes of the agent (no Docker needed): the agent installs a Python 3.12
environment with PyTorch for CUDA 13 per engine with `uv` (about 5 GB, once; the first job waits for it), fetches the engine's
code and the model files (resumable). A machine can still run its engines in Docker containers started by `wxch-runner`:
put `"mode": "docker"` into `<modules folder>/state.json`. Engines start when a job arrives and stop after 10 idle minutes; they never stop the chat:
GPU work in these containers is not mistaken for the owner. People use them on `studio.wxch.org` (same password as the
chat); a capability is listed as offered only while an online machine has it installed.

ผู้ให้บริการเลือกเองว่าเครื่องไหนเปิดบริการภาพ/วิดีโอ/เสียง **ไม่ได้ติดตั้งมาให้**: ใช้ `WXCH_MODULES=...` ตอนติดตั้ง
หรือ `get | sh -s -- modules <ชื่อ|all>` ทีหลัง หรือกดติดตั้งในหน้า "โมดูล AI" ของ control (เห็นขนาดรวมก่อนติดตั้ง)

## External disks for models / ดิสก์ external สำหรับเก็บโมเดล

Any number of USB disks can be added, one at a time, whenever you like. Adding a disk needs no token, no reinstall and
restarts nothing (a running download or a loaded model is not disturbed).

```
curl -fsSL https://YOUR-SERVER/get | sh -s -- add-disk                  # list the disks that can be added
curl -fsSL https://YOUR-SERVER/get | sh -s -- add-disk /dev/sdb1        # add one (asks for sudo once)
```

- **A disk that already holds files (ext4, xfs or btrfs) is added as it is:** nothing on it is changed or erased. The
  models go into one folder, `wxch-models`, on the disk. The disk is found by its UUID, so the device name does not matter.
- **A new or unsuitable disk** (empty, or NTFS/exFAT/FAT, which cannot keep Unix permissions) is refused with an
  explanation. To use it anyway you have to ERASE it explicitly:
  `curl -fsSL https://YOUR-SERVER/get | WXCH_CONFIRM=ERASE sh -s -- add-disk /dev/sdb1 --format`.
  Only USB disks are accepted (`WXCH_ALLOW_NON_USB=1` allows others); the disk the system runs from is always refused.
- `--name backup` chooses the disk's id (default `d1`, `d2`, ...). Running the command again for a disk that is already
  added just checks it. The disks are mounted on demand at `/mnt/wxch-ext/<id>`.
- **Where downloads go:** every model downloaded through the web UI goes to a connected external disk (the one with the
  most room) when there is one (Ollama and vLLM models). The three starter models stay on the machine; when they finish
  downloading the web UI asks where to keep them and waits 20 seconds (no answer = on the machine). During the installer the
  same question is asked on the terminal when a disk is connected.
- **Move or tidy up:** the Models page shows, for every machine at once, where each model is (the machine or which disk),
  with a button to move it to any connected disk or back. A model that exists in more than one place is listed under
  "Duplicates": keep any one copy.
- **Unplugging:** models on a disk disappear from the machine's list and from routing until it is plugged in again.
  Plug the disk into a reinstalled machine (add-disk once) and its models are taken over automatically (Ollama needs
  the internet once to fetch the small model description).
- LM Studio models are not moved yet (they always stay on the machine).