# wxch: run AI on your own GPU machines

**ไทย:** ระบบสำหรับเปิดใช้ AI บนเครื่อง GPU ของคุณเอง (เช่น NVIDIA DGX Spark / "PGX") โดยไม่ต้องพึ่งคลาวด์ของผู้ให้บริการรายใหญ่
ควบคุมจากหน้าเว็บเดียว: เปิดเทอร์มินัลบนเครื่อง จัดการโมเดล คุยกับโมเดลในแชต ใช้ API แบบเดียวกับ OpenAI และ (ถ้าเลือก)
สร้างภาพ วิดีโอ และถอดเสียง ติดตั้งเครื่อง GPU ใหม่ด้วยคำสั่งเดียว

**English:** a small self-hosted system to use the GPU machines you own. One web page to open a terminal on a machine, manage its
models, chat with them, call them through an OpenAI-compatible API and, optionally, make images, video and transcripts.
A new GPU machine is added with one command. No vendor cloud and no Tailscale.

> Status: written and used on one NVIDIA DGX Spark (GB10, arm64). Other machines are covered by installer tests in containers, not by
> real hardware. What is verified and what is not is stated in [docs/INSTALL.md](docs/INSTALL.md) and below.

## How it fits together

```
 you (browser / API client)
        │  HTTPS
        ▼
 ┌─────────────────────────┐        ┌──────────────────────────────┐
 │ wxch-server  (a small   │◄───────│ wxch-agent on each GPU machine│
 │ VPS with a domain)      │  the   │  - terminal, status, models   │
 │  web UI, chat, API,     │ agent  │  - Ollama / LM Studio / vLLM   │
 │  studio, installer      │ dials  │  - optional ComfyUI / Whisper  │
 └─────────────────────────┘  out   └──────────────────────────────┘
```

The GPU machine **dials out** to the server, so it needs no open port and no VPN. The server never needs to log in to the machine.

## Quick start

1. **Server** (a small VPS with a domain and HTTPS; see [docs/DNS.md](docs/DNS.md), Caddy example in `deploy/server/`):
   build with `scripts/build.sh`, create the config with `wxch-server -init -config config.json -password <a long password>`
   and add a machine with `wxch-server -config config.json -add-agent <name>`. It prints the install command for that machine.
2. **Each GPU machine:** run the printed command in a terminal on the machine (it asks for `sudo` once):

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

   It installs the agent, Ollama, LM Studio and vLLM (what the machine can run), downloads one small model of each and runs a self-test.
   It is safe to run again. `sh -s -- --dry-run` shows the plan without changing anything.
3. **Optional AI modules** (image, video, speech): tick them on the control page ("AI modules"), or
   `curl -fsSL https://YOUR-SERVER/get | sh -s -- modules image.generate`. Nothing of this is installed by default; the big model files
   are shown with their size before you choose.

Details, supported systems and options: [docs/INSTALL.md](docs/INSTALL.md).

## What is in it

| Part | Folder | What it does |
|---|---|---|
| Server | `cmd/wxch-server`, `web/` | web UI, agent hub, OpenAI-compatible gateway, chat, notepad, studio, installer endpoints |
| Agent | `cmd/wxch-agent` | on each GPU machine: terminal, telemetry, model pool, runtimes, temperature limits, "owner first" guard |
| Runner | `cmd/wxch-runner` | tiny root helper that starts vLLM containers for the agent (locked-down, allow-listed flags) |
| Installer | `deploy/files/` | the one-command install, add-disk, uninstall |
| Model lists | `catalog/` | recommended chat models (`catalog.json`) and the image/video/speech modules (`modules.json`, `workflows/`) |
| Docs | `docs/` | install, DNS, API, design (some in Thai); [AI guide (Thai)](docs/AI-GUIDE-TH.md): models, what was tested, troubleshooting, suggestions |

## Models

`catalog/catalog.json` lists chat models with their real sizes and licences (read from the registries, not guessed). On the author's DGX Spark
NVIDIA Nemotron 3 Super 120B and Nemotron 3.5 Super VL 120B (vLLM, NVFP4) have been run and answered in the chat; Qwen3-Coder-Next is installed there. Other entries are listed
but **not tried** on real hardware yet; their notes say so. Image generation uses FLUX.1-schnell (Apache-2.0) and video uses Wan 2.2 through ComfyUI.
Model files come from their own publishers; check each licence before you use a model.

## Safety, in short

- The agent cannot run vLLM flags the runner has not allowed. Running code that ships inside a model repository (`--trust-remote-code`) is
  off, and can be turned on only for named models by the machine's root user (`trust_remote_code` in `/etc/wxch/runner.json`).
- Model files of the AI modules are checked against the publisher's sha256 after the download (a damaged copy of the right size is removed and fetched again).
- The machine's owner comes first: when the owner is using the machine, new work waits and models are unloaded.
- Never put tokens, passwords or keys in this repository. `.gitignore` covers the usual files.

## Known gaps

See [docs/CHAT-GAPS.md](docs/CHAT-GAPS.md) for what the chat page still lacks (downloads, file attachments, making images from the chat).
Real-hardware checks still open: speed and memory of the newest models, image and video quality tuning on the GB10.

## Working together

How decisions are made is written in [GOVERNANCE.md](GOVERNANCE.md). **A software licence has not been chosen yet.** Until one is added
(a `LICENSE` file), you may read this code but have no permission to copy, run or redistribute it.

## For developers

```
go vet ./... && go test ./...      # needs Go (see go.mod)
scripts/build.sh                   # builds dist/ (server amd64; agent and runner for amd64 and arm64)
bash tests/installer/run.sh ubuntu:24.04   # installer test in Docker
```

Edit the pages in `web/static/`, add a model by adding one entry to `catalog/catalog.json`. Match the surrounding code style and keep
comments to the non-obvious "why".