Installation · advanced
Advanced install
Each part by hand, layouts with more than one machine or site, and what to do once it runs. INSTALL.md has every procedure in full; this page is the map, with the commands you'll need most and links to the detail.
Applies to 0.1.0-alpha.2For one PC with the wizard, see the general setup
1. Before you start
The order is the same on every layout: check the machines, get and verify the source, download the images, install the Forge, install the Workstation, sign every part in to Tailscale, pair the parts, and verify. INSTALL.md sections 2 to 9 follow that order.
The inventory reports what a machine can run and changes nothing. Run it on each machine with the role it will
play: workstation-host, gpu-host, all or agent.
Linux
bash install/deep32-inventory.sh --journey J4 --role all --check-prereqsWindows
powershell -NoProfile -ExecutionPolicy Bypass -File install\deep32-inventory.ps1 -Journey J1 -Role workstation-host -CheckPrereqsThe report ends with a verdict for that role and, for a GPU host, the card class you'll pass to
deep32-get. Anything missing is listed with what to install. Get the source as in
step 2 of the general setup: a clone at the release tag, its signature checked
(INSTALL section 3).
With an agent
On any layout, Claude Code's /deep32-install or Codex's $deep32-install, run in the
clone, works through the same steps on that machine following
AGENTS.md. It asks before it changes
anything; passwords, sign-in clicks and pairing codes stay yours.
2. Layouts
A deployment has three parts: the Workstation, the Forge and the headend (the PC where Claude Code or Codex runs). They can share machines. The installers call each layout a journey:
| Journey | Machines | Workstation and Forge | In 0.1.0-alpha.2 |
|---|---|---|---|
| J1 | Two Windows PCs | Hyper-V VM on the first; Docker Desktop on the second | Not yet run end to end |
| J2 | A Windows PC and a Linux NVIDIA host | Hyper-V VM on the Windows PC; Docker on the Linux host | The Linux Forge is tested; the Hyper-V Workstation isn't yet |
| J3 | One Linux NVIDIA host, no desktop | No Workstation: engine and gateway in Docker, with the Forge | Not in this release: its image isn't among the downloads |
| J4 | One Linux NVIDIA host | KVM VM and Docker on the same host | The tested parts: a KVM Workstation and a Docker Forge on Linux |
What I have run is a Workstation in a KVM virtual machine on Proxmox, with a Forge on a separate Linux host. The other rows put the same parts in different places. The headend can be any of these machines or another PC. The general setup's one PC is J4 on Linux; on Windows it puts J1's two halves on one PC.
3. Downloads
deep32-get downloads an image, checks it against the release's signed metadata, and keeps it only if
every check passes. It tries the Internet Archive first and then each mirror in the signed list, and it resumes an
interrupted download from the last verified 64 MiB chunk.
| Image | Size | Needed for | Command |
|---|---|---|---|
| Disc 1, Workstation | 1.9 GB | J1, J2, J4 | bash src/release-tools/deep32-get.sh disc1 |
| Disc 2, content | 19.6 GB | Every journey | bash src/release-tools/deep32-get.sh disc2 |
| Disc 3, Forge GPU pack | about 37.1 GB | Forge installs | bash src/release-tools/deep32-get.sh disc3 --gpu-class CLASS --ingestion |
On Windows use src\release-tools\deep32-get.ps1 with the same arguments. Files go to
./deep32-downloads unless you give --to DIR. For disc 3 you get three images: the shared
core (18.6 GB), your card's embedder (3.1 to 3.3 GB) and ingestion (15.3 GB). The alpha.2 Forge installer needs all
three. Your card's class comes from its compute capability:
nvidia-smi --query-gpu=compute_cap --format=csv,noheader| Compute capability | 7.5 | 8.0 | 8.6, 8.7 | 8.9 | 9.0 | 10.0 | 12.0 |
|---|---|---|---|---|---|---|---|
| Disc 3 class | turing | ampere80 | ampere86 | ada | hopper | blackwell100 | blackwell120 |
If every mirror fails, deep32-get prints the image's torrent address from the signed metadata.
Download it with any torrent client, then check it with --from DIR, which verifies files you already
have without downloading them. You don't have to trust deep32-get: the
README's section 11 shows how to check
an image by hand with gpgv and SHA-256.
Disc 2 can also reach the Workstation without a download on your side: the Workstation fetches it from a PC on your tailnet or from the Internet Archive mirror (general setup, step 6).
4. By hand, layout by layout
Run these from the verified clone. CLASS is your card's class from section 3. The VM commands that
--prepare-vm writes still make a 160 GB disk: change 160GB (Hyper-V) or 160G
(KVM) to 200GB or 200G before you run them.
J4One Linux NVIDIA host
The Workstation in a KVM VM and the Forge in Docker, on the same Ubuntu 24.04 host.
bash src/release-tools/deep32-get.sh disc1
bash src/release-tools/deep32-get.sh disc1 --prepare-vm --hypervisor kvm
bash src/release-tools/deep32-get.sh disc2
bash src/release-tools/deep32-get.sh disc3 --gpu-class CLASS --ingestion
sudo bash src/release-tools/deep32-get.sh disc3 --gpu-class CLASS --install --journey J4 --data-root /opt/deep32 --from ./deep32-downloadsJ2A Windows PC and a Linux NVIDIA host
On the Windows PC, the Workstation's host:
powershell -NoProfile -ExecutionPolicy Bypass -File src\release-tools\deep32-get.ps1 disc1
powershell -NoProfile -ExecutionPolicy Bypass -File src\release-tools\deep32-get.ps1 disc1 --prepare-vm --hypervisor hyper-v
powershell -NoProfile -ExecutionPolicy Bypass -File src\release-tools\deep32-get.ps1 disc2On the Linux host, the Forge:
bash src/release-tools/deep32-get.sh disc3 --gpu-class CLASS --ingestion
sudo bash src/release-tools/deep32-get.sh disc3 --gpu-class CLASS --install --journey J2 --data-root /opt/deep32 --from ./deep32-downloadsJ1Two Windows PCs
On the first PC, the Workstation's host: the same three lines as J2's Windows PC. On the second PC, the Forge, from an elevated PowerShell with Docker Desktop running:
powershell -NoProfile -ExecutionPolicy Bypass -File src\release-tools\deep32-get.ps1 disc3 --gpu-class CLASS --ingestion
powershell -NoProfile -ExecutionPolicy Bypass -File src\release-tools\deep32-get.ps1 disc3 --gpu-class CLASS --install --journey J1 --data-root C:\Deep32 --from .\deep32-downloadsIf Docker Desktop keeps its disk image somewhere other than its default, add --docker-storage-path
DIR so the space check looks at the right drive.
J3One Linux host, everything in Docker
Not in this release: its image isn't among the downloads. A layout with everything in Docker on one Linux host, with no VM, is on the roadmap.
The Forge installer wants the three images in one folder with the five signed files of the same release:
SHA256SUMS, SHA256SUMS.sig, MIRRORS.json, CAPABILITIES.json and
FORGE-PREREQUISITES.json. deep32-get already put them in ./deep32-downloads,
the signed files in its .deep32-v0.1.0-alpha.2/revision-* snapshot. Before it changes anything the
installer checks the host recipe, the driver and memory floors, the Forge's ports and the free space, asks you to
confirm the tailnet and the Certificate Transparency agreement, and shows its plan. Type the plan digest to go on.
From there, INSTALL.md has each part in full: the Forge, the Workstation (VM settings, the guided install and first boot), Tailscale, pairing and Connect and verification.
5. Disk space
The Workstation needs a disk of 200 GB or more. The guided layout sizes the Library partition from the disk, and the disc 2 import needs about 20 GB free there. Its downloads are 21.5 GB.
The Forge installer compares free space with the storage budget signed into the release. For 0.1.0-alpha.2
the budgets are declared upper bounds, computed from the sizes of the three images with a margin over what my test
runs used; the check line ends with (declared upper bound; no measurement yet). The installer checks
twice, before it joins the images and again after it has written the joined copy (36.8 GB), each time against the
whole budget. So have the budget plus the joined copy free when you start:
| Where the Forge writes | Budget | Free at the start |
|---|---|---|
| Linux, data folder and Docker's storage on one filesystem | 244.0 GB | 280.8 GB |
| Linux or Windows, the data folder on a filesystem or volume of its own | 123.8 GB | 160.6 GB |
| Linux, Docker's storage on a filesystem of its own | 120.2 GB | 120.2 GB |
| Windows, data folder and Docker Desktop's disk image on one volume | 246.2 GB | 283.0 GB |
| Windows, Docker Desktop's disk image on a volume of its own | 122.5 GB | 122.5 GB |
| Windows, inside Docker Desktop's virtual disk | 176.8 GB | 176.8 GB |
- The figures are for a
turingcard; the other classes need up to about 1 GB more. - GB here means 109 bytes.
df -hand Windows count in GiB and show numbers about 7% smaller. - The joined copy goes beside the data folder, in
/opt/deep32.deep32-mediafor/opt/deep32. If the data folder is a mount point of its own, the joined copy lands on the filesystem above it.
INSTALL section 5 has the measured run behind these numbers.
6. Ports
Every part publishes its services inside your tailnet only, with Tailscale Serve. No port is opened to the internet.
| Port | Part | Reached from | Used for |
|---|---|---|---|
| 443, 8443 (HTTPS) | Forge | The tailnet | The Forge's door. Without a token it answers 401 |
| 8081, 8082 | Forge | The Forge itself (127.0.0.1) | The embedding and reranking servers behind the door |
| 7453 | Forge | The Workstation, while a pairing window is open | The pairing window |
| 443 (HTTPS) | Workstation | The tailnet | The published gateway, https://<workstation>.<tailnet>.ts.net/mcp |
| 7452 (TCP) | Agent PC | The Workstation, over the tailnet | The Ask link to the relay. The Workstation's firewall allows only this relay port |
The Forge installer checks that its ports are free, or already this Forge's, and refuses a port or route another service already uses. The plan it shows lists the ports it will take. The inventory checks 8765, 8766, 8443, 8081, 8082 and 7452 on the machine it runs on and reports any that are busy.
7. Tailnet names and rules
- Your own tailnet. Every part joins your tailnet with your own Tailscale account. No auth key is on any image or in the repository, and the free plan is enough.
- MagicDNS and HTTPS certificates must be on. The installers check both and name the one that's off; they never change tailnet settings themselves.
- Names in public logs. With HTTPS certificates on, machine names appear in the public Certificate
Transparency logs, so give your nodes names that say nothing about you. Publication asks you to agree to this once
(
--accept-ct). - The
deep32-prefix. The Workstation offers only machines whose Tailscale name starts withdeep32-, for both the Forge and the Ask relay. Rename a machine on the admin console's Machines page or withsudo tailscale set --hostname deep32-forge. - One tailnet. The Workstation offers only machines in its own tailnet. A machine shared in from someone else's tailnet is never offered for pairing.
- Which node is the Forge. A Forge in Docker Desktop uses its Windows host's node. A Forge in a WSL 2 distro runs Tailscale inside the distro and is a node of its own.
- Key expiry. Tailscale expires a device's sign-in after 180 days by default. Choose Disable key expiry for these devices on the Machines page to avoid signing in again.
- Access rules. The default policy allows everything. With rules of your own, allow the agent PC to reach the Workstation's gateway, the Workstation to reach the Forge, and the Workstation to reach the relay on TCP port 7452.
- Serve on Linux. The relay needs your user to manage Tailscale Serve:
sudo tailscale set --operator=$USER, once. - Device approval. If your tailnet approves new devices by hand, approve each Deep32 machine on the
Machines page; the Forge's setup stops with
tailscale-approvaluntil you do.
INSTALL section 7 has the details.
8. The Forge on Docker Desktop or Docker Engine
The GPU pack is one Linux Docker form on every host. On Windows it runs through Docker Desktop or in an Ubuntu 24.04 WSL 2 distro.
| Docker Engine (Linux or WSL 2) | Docker Desktop (Windows) | |
|---|---|---|
| Host | Ubuntu 24.04 on amd64, on the host or as a WSL 2 distro with systemd on | Windows 11 build 26100 or later: Home, Pro, Enterprise or Education |
| Software | Docker Engine with the Compose v2 plugin and the NVIDIA Container Toolkit | Docker Desktop 4.99.0 or later with Docker Engine 29.0.0 or later, WSL 2 backend |
| Journeys, recipe | J2, J4: ubuntu-24.04-docker-engine-j2, -j4 | J1: windows-11-docker-desktop-wsl2-j1 |
| Graphics driver | NVIDIA 580.65.06 or newer | The Windows driver, 580.65.06 or newer, serves Docker Desktop; no Linux driver inside its WSL 2 backend |
| Classic image store | "features": {"containerd-snapshotter": false} in /etc/docker/daemon.json, then restart Docker | Settings, General: turn off Use containerd for pulling and storing images |
| Tailscale node | The host's own; in WSL 2, the distro is a node of its own | The Windows host's node |
| Install from | sudo bash, data folder /opt/deep32 in INSTALL's examples | An elevated PowerShell with Docker Desktop running, data folder C:\Deep32 |
| Pairing code | sudo grep -o 'pair=[A-Z2-7]*' /opt/deep32/status/status | The helper forge_pair_windows.py; the code is in C:\Deep32\status\windows-pair |
| Pairing helper's Python | The host's /usr/bin/python3, 3.10 or newer with ssl | Started with python -I -B from the clone |
| What has run | On an RTX 2080 Ti in an Ubuntu 24.04 WSL 2 distro: the images and their join, both models, the Workstation's check of both models, and a one-page PDF converted with --tier standard in about 2 minutes 22 seconds | The images joined and loaded into Docker Desktop. No model has run there yet |
Both install under an owner waiver for this release, ahead of their full end-to-end runs, and the installer
prints a note that says so; FORGE-PREREQUISITES.json lists what wasn't run for each host type.
Appliance systems with a read-only root, such as Unraid, can't host an alpha.2 Forge, because the pairing helper
needs the host's own Python. HARDWARE
section 5 lists the cards.
9. A bare-metal Workstation
For a physical install, the tested laptop is the Dell Latitude 5430; other machines run the Workstation as a VM. In the wizard's VM guide, Other hypervisor or bare metal lists the settings and has you confirm each step.
- Disc 1 is a disk image. Write it byte for byte to a USB stick of at least 2 GB, for example with
dd, or Rufus in DD image mode, and boot the machine from it. - The install disk must be empty and at least 200 GB. The installer erases it and asks you to type its name to confirm. It can encrypt it.
- The network: one wired network card on a network with DHCP and internet. OpenBSD drives Intel PRO/1000 (em), VirtIO (vio), VMXNET3 (vmx) and Hyper-V (hvn) network cards.
- The processor: 64-bit Intel or AMD. Low-power chips of the Atom, Celeron or Pentium Silver class are too slow for the engine, gateway, desktop and Library together.
- Disc 2: a 25 GB BD-R in a Blu-ray drive, a USB stick of 32 GB or more, or over the network.
- Administration happens at the console. Maintenance over SSH is off unless you give the installer an Ed25519 public key; with one, a separate SSH server accepts that key for root, only from the tailnet address of the machine the Workstation is paired with.
10. More than one site
The parts talk over your tailnet, so the Workstation, the Forge and the agent PC can be in different places. At home on one LAN the connections are direct. Across sites they still work, and the speed depends on whether Tailscale gets a direct path or relays.
tailscale statusshowsdirectorrelayfor each peer. A relayed path adds tens of milliseconds to every search: on my setup, latency between the parts was 70 to 157 ms through a relay and 1 to 2 ms direct.- Tailscale needs outbound UDP for direct paths. With UDP blocked it falls back to relays over HTTPS.
- A Workstation VM on NAT works, but Tailscale may relay when it can't connect directly, which is slower for Ask, the Library and the Forge. Bridged is the faster choice.
- A remote Forge is the part most likely to be off or unreachable. After three failed calls in a row the engine
stops waiting on it and lets one trial call through every 30 seconds; meanwhile keyword search serves alone and
the response names the missing services in its
degradedfield. - Pairing works the same across sites. The five-minute code still applies, and every machine has to be in the
Workstation's own tailnet with a
deep32-name where one is needed. - Disc 2 can reach a remote Workstation from any PC on your tailnet, or from the Internet Archive mirror.
- If you use access rules of your own, allow the paths in section 7.
11. Afterwards: start, stop, upgrade, uninstall
Status. bash install/deep32-setup.sh check can be run at any time; it never changes
anything.
The Forge on Linux keeps the kit it was installed from under
/opt/deep32/releases/RELEASE/kit, and every later action runs from there.
cat /opt/deep32/startup-hook-v1.sh names the current RELEASE.
K=/opt/deep32/releases/RELEASE/kit
sudo bash $K/forms/load-docker.sh --status --docker-role forge --data-root /opt/deep32
sudo bash $K/forms/load-docker.sh --start --docker-role forge --data-root /opt/deep32
sudo bash $K/forms/load-docker.sh --stop --docker-role forge --data-root /opt/deep32
sudo bash $K/forms/load-docker.sh --resume --docker-role forge --data-root /opt/deep32
sudo python3 -I -B $K/forms/forge_docker_role.py uninstall --data-root /opt/deep32--status prints one JSON line: whether the three services are healthy, whether the routes are
published, and the next step. Each start of an unpaired Forge opens a new five-minute pairing window.
| Task | What to do in 0.1.0-alpha.2 |
|---|---|
| Upgrade the Forge | Its --upgrade action installs new GPU media over the old and keeps the Forge's data and pairing identity. A Forge installed fresh into an empty folder makes a new token and certificate, so pair it with the Workstation again afterwards |
| Upgrade the Workstation | In the alpha releases a Workstation is installed fresh. Upgrading covers moving an install to a new release |
| Revoke a Workstation on the Forge | Revoking rotates the Forge's token, and the Forge then refuses to restart. Until 0.1.0-alpha.3, revoke by uninstalling the Forge and installing it into a new data folder, then pair again |
| Remove the Forge | Revoke it on the Workstation first. The uninstall action stops the Forge and takes off its Serve routes and startup launcher, and keeps the data folder, its keys and the loaded Docker images. Then delete the data folder and remove the deep32-local/* images yourself |
| Remove the Workstation | Remove its VM with the hypervisor |
| Remove a headend | Close its agent sessions, revoke it in the Workstation's Pairing by the install ID Connect printed, and delete its profile folder if it had one |
| Remove the Ask relay | bash adapters/connect.sh --relay remove --relay-id '<id>' --agent claude --tailscale-binary "$(command -v tailscale)" |
Optional features that would contact anything ship off; Optional Features lists each one and what it would contact. INSTALL section 10 has the rest.
12. Troubleshooting by error code
When a step fails, the wizard shows a code, what happened and up to five fix steps, each saying where to do it.
Both wizards read the same table,
install/deep32-wizard-errors.tsv.
Each row names the tool that prints the code: the setup script, deep32-get, the inventory, the Forge
installer, Connect, the relay, Docker, Tailscale, or the wizard's own VM checks. Search the table for the code you
see. Press L in the wizard for its log, which is kept in ~/.local/state/deep32-setup or
%LOCALAPPDATA%\Deep32-setup.
| Code | From | What happened | Fix |
|---|---|---|---|
VM_FIRMWARE_UEFI, VM_GENERATION | VM guide | The VM boots with UEFI | Set BIOS firmware; on Hyper-V, create a Generation 1 VM |
VM_DISK_SMALL | VM guide | The largest disk is under 200 GB | Give the VM an empty disk of at least 200 GB |
VM_DISPLAY_VIRTIO | VM guide | The VM has a virtio-gpu display | Set a standard VGA display |
NET_HOSTONLY | VM guide | Host-only, internal or private network: no internet for the sign-in | Use a bridged or NAT network |
KIT_MISSING | VM guide | No verified disc 1 with deep32-get's VM folder | Run the deep32-get disc1 --prepare-vm line it shows, then the guide again |
TS_NOT_HERE, TS_PEER_MISSING | VM guide | The wizard can't see the Workstation join | Finish the sign-in on the Workstation; if it stalls, give the VM another DNS server |
docker-store-containerd | deep32-get | Docker uses its containerd image store | Switch to the classic store (section 8) |
gpu.memory | Inventory | The card has less memory than the signed plan needs | Use a card with 11 GB or more |
gpu.ports | Inventory | A Forge port is taken by another program | Stop that program, or give the Forge other ports |
host.magicdns, host.https-certificates | Inventory | MagicDNS or HTTPS Certificates is off | Turn it on in the admin console's DNS page |
windows.edition | Inventory | This Windows edition can't run the Workstation VM | Hyper-V needs Pro, Enterprise or Education |
tailscale-approval | Forge | The device waits for approval in your tailnet | Approve it on the Machines page |
expired, unreachable | Connect | The pairing code expired, or the Workstation's pairing service wasn't reachable | Open a new Headend pairing and type the code within five minutes |
agent-sign-in-required | Relay | The relay's agent is signed out | Sign the relay's profile in again |
IMPORT_SPACE, IMPORT_KB_ONLY | Workstation import | The Library didn't fit, or its part failed; the knowledge base stays in use | Use a 200 GB disk; Import Report says what happened |
INSTALL.md gives the recovery for each part where its procedure is, the Agent Adapters troubleshooting table covers Connect and the gateway, and the release notes list this release's known issues.
13. What is never stored
No image, release file or file in the repository holds a secret key, token, password or sign-in. The only keys
that ship are public halves, such as the release key in install/. Each install makes its own:
- your Tailscale membership, at your sign-in on each node;
- the Workstation's engine token, at its first boot, which never leaves it;
- a gateway token for each agent, on the Workstation, when that agent pairs;
- the Forge's token and bundle signing key, at its first boot. The token, and the public half of the key, go to the Workstation at pairing;
- the Ask link keys, on each side, with the pins exchanged at pairing.
Your Claude Code, Codex and GitHub sign-ins stay in those tools' own stores. INSTALL section 11 has the table.