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-prereqs

Windows

powershell -NoProfile -ExecutionPolicy Bypass -File install\deep32-inventory.ps1 -Journey J1 -Role workstation-host -CheckPrereqs

The 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:

JourneyMachinesWorkstation and ForgeIn 0.1.0-alpha.2
J1Two Windows PCsHyper-V VM on the first; Docker Desktop on the secondNot yet run end to end
J2A Windows PC and a Linux NVIDIA hostHyper-V VM on the Windows PC; Docker on the Linux hostThe Linux Forge is tested; the Hyper-V Workstation isn't yet
J3One Linux NVIDIA host, no desktopNo Workstation: engine and gateway in Docker, with the ForgeNot in this release: its image isn't among the downloads
J4One Linux NVIDIA hostKVM VM and Docker on the same hostThe 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.

ImageSizeNeeded forCommand
Disc 1, Workstation1.9 GBJ1, J2, J4bash src/release-tools/deep32-get.sh disc1
Disc 2, content19.6 GBEvery journeybash src/release-tools/deep32-get.sh disc2
Disc 3, Forge GPU packabout 37.1 GBForge installsbash 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 capability7.58.08.6, 8.78.99.010.012.0
Disc 3 classturingampere80ampere86adahopperblackwell100blackwell120

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-downloads

J2A 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 disc2

On 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-downloads

J1Two 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-downloads

If 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 writesBudgetFree at the start
Linux, data folder and Docker's storage on one filesystem244.0 GB280.8 GB
Linux or Windows, the data folder on a filesystem or volume of its own123.8 GB160.6 GB
Linux, Docker's storage on a filesystem of its own120.2 GB120.2 GB
Windows, data folder and Docker Desktop's disk image on one volume246.2 GB283.0 GB
Windows, Docker Desktop's disk image on a volume of its own122.5 GB122.5 GB
Windows, inside Docker Desktop's virtual disk176.8 GB176.8 GB
  • The figures are for a turing card; the other classes need up to about 1 GB more.
  • GB here means 109 bytes. df -h and Windows count in GiB and show numbers about 7% smaller.
  • The joined copy goes beside the data folder, in /opt/deep32.deep32-media for /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.

PortPartReached fromUsed for
443, 8443 (HTTPS)ForgeThe tailnetThe Forge's door. Without a token it answers 401
8081, 8082ForgeThe Forge itself (127.0.0.1)The embedding and reranking servers behind the door
7453ForgeThe Workstation, while a pairing window is openThe pairing window
443 (HTTPS)WorkstationThe tailnetThe published gateway, https://<workstation>.<tailnet>.ts.net/mcp
7452 (TCP)Agent PCThe Workstation, over the tailnetThe 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 with deep32-, for both the Forge and the Ask relay. Rename a machine on the admin console's Machines page or with sudo 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-approval until 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)
HostUbuntu 24.04 on amd64, on the host or as a WSL 2 distro with systemd onWindows 11 build 26100 or later: Home, Pro, Enterprise or Education
SoftwareDocker Engine with the Compose v2 plugin and the NVIDIA Container ToolkitDocker Desktop 4.99.0 or later with Docker Engine 29.0.0 or later, WSL 2 backend
Journeys, recipeJ2, J4: ubuntu-24.04-docker-engine-j2, -j4J1: windows-11-docker-desktop-wsl2-j1
Graphics driverNVIDIA 580.65.06 or newerThe 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 DockerSettings, General: turn off Use containerd for pulling and storing images
Tailscale nodeThe host's own; in WSL 2, the distro is a node of its ownThe Windows host's node
Install fromsudo bash, data folder /opt/deep32 in INSTALL's examplesAn elevated PowerShell with Docker Desktop running, data folder C:\Deep32
Pairing codesudo grep -o 'pair=[A-Z2-7]*' /opt/deep32/status/statusThe helper forge_pair_windows.py; the code is in C:\Deep32\status\windows-pair
Pairing helper's PythonThe host's /usr/bin/python3, 3.10 or newer with sslStarted with python -I -B from the clone
What has runOn 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 secondsThe 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 status shows direct or relay for 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 degraded field.
  • 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.

TaskWhat to do in 0.1.0-alpha.2
Upgrade the ForgeIts --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 WorkstationIn the alpha releases a Workstation is installed fresh. Upgrading covers moving an install to a new release
Revoke a Workstation on the ForgeRevoking 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 ForgeRevoke 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 WorkstationRemove its VM with the hypervisor
Remove a headendClose 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 relaybash 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.

CodeFromWhat happenedFix
VM_FIRMWARE_UEFI, VM_GENERATIONVM guideThe VM boots with UEFISet BIOS firmware; on Hyper-V, create a Generation 1 VM
VM_DISK_SMALLVM guideThe largest disk is under 200 GBGive the VM an empty disk of at least 200 GB
VM_DISPLAY_VIRTIOVM guideThe VM has a virtio-gpu displaySet a standard VGA display
NET_HOSTONLYVM guideHost-only, internal or private network: no internet for the sign-inUse a bridged or NAT network
KIT_MISSINGVM guideNo verified disc 1 with deep32-get's VM folderRun the deep32-get disc1 --prepare-vm line it shows, then the guide again
TS_NOT_HERE, TS_PEER_MISSINGVM guideThe wizard can't see the Workstation joinFinish the sign-in on the Workstation; if it stalls, give the VM another DNS server
docker-store-containerddeep32-getDocker uses its containerd image storeSwitch to the classic store (section 8)
gpu.memoryInventoryThe card has less memory than the signed plan needsUse a card with 11 GB or more
gpu.portsInventoryA Forge port is taken by another programStop that program, or give the Forge other ports
host.magicdns, host.https-certificatesInventoryMagicDNS or HTTPS Certificates is offTurn it on in the admin console's DNS page
windows.editionInventoryThis Windows edition can't run the Workstation VMHyper-V needs Pro, Enterprise or Education
tailscale-approvalForgeThe device waits for approval in your tailnetApprove it on the Machines page
expired, unreachableConnectThe pairing code expired, or the Workstation's pairing service wasn't reachableOpen a new Headend pairing and type the code within five minutes
agent-sign-in-requiredRelayThe relay's agent is signed outSign the relay's profile in again
IMPORT_SPACE, IMPORT_KB_ONLYWorkstation importThe Library didn't fit, or its part failed; the knowledge base stays in useUse 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.