Installation · general setup

General setup

This page sets up Deep32 the common way. One PC with an NVIDIA card runs the Forge and your agent, the Workstation runs as a VM on the same PC, and all of it joins one tailnet. The setup wizard drives each part and checks each step. Where your setup is different, the step says what changes.

Applies to 0.1.0-alpha.2Plan on an afternoon, most of it downloadingEvery step by hand: INSTALL.md

The parts of Deep32: the headend, your agent on your PC; the Workstation for search and archive, disc 1; the Forge, the GPU powerhouse, disc 3; the Ask relay, the link between the Ask window and your agent; and the content, the library on disc 2.
Figure 1. The parts and the discs they come from. On this page the agent, the Forge and the Workstation's VM share one PC.

What I have tested

The Workstation installs from its image on a clean VM: the guided install, first boot, Tailscale and publishing the gateway. My lab VM runs on Proxmox. The Forge installs from the signed images on Linux, in WSL 2 and on Docker Desktop; I checked each of its parts on an RTX 2080 Ti, and the full run on each kind of host follows the release. The wizard's VM guide is boot-tested on Proxmox VE only. I haven't yet run the setup from start to finish on a clean machine, so if a step fails here, the same step by hand in INSTALL.md is the tested path.

Step 1: Before you start

Where: your PC and a browserA checklist

What you need

Do this

  1. In the Tailscale admin console, open the DNS page (login.tailscale.com/admin/dns) and turn on MagicDNS and HTTPS Certificates. Deep32 publishes its services with Tailscale Serve over HTTPS, which needs both. The installers check them and name the one that's off; they never change tailnet settings themselves.
  2. With HTTPS certificates on, machine names appear in the public Certificate Transparency logs. Give your machines names that say nothing about you.
  3. Sign the PC in to Tailscale and give it a machine name that starts with deep32-, for example deep32-forge. The Workstation only offers machines named that way for pairing. Rename it on the admin console's Machines page, or on Linux:
    sudo tailscale set --hostname deep32-forge
  4. Optional: Tailscale expires a device's sign-in after 180 days by default. To avoid signing in again, choose Disable key expiry for your Deep32 machines on the Machines page.

What you should see

The DNS page shows MagicDNS and HTTPS Certificates on, and tailscale status on the PC lists it under its deep32- name.

If it doesn't

  • Not sure about the card? These print its compute capability and its memory in MiB. The Forge needs 10752.
    nvidia-smi --query-gpu=compute_cap --format=csv,noheader
    nvidia-smi --query-gpu=memory.total --format=csv,noheader,nounits
  • The wizard checks this list again in step 3 and says what's missing, so an open box isn't a reason to stop here.

Step 2: Get Deep32

Where: the PC, in a terminal

What you need

Git, and GnuPG to check the release tag's signature.

Do this

  1. Clone the repository at the release tag and check the tag's signature.

    Linux

    git clone --branch v0.1.0-alpha.2 https://github.com/hellobpdu/deep32.git
    cd deep32
    gpg --import install/release-key.asc
    git verify-tag v0.1.0-alpha.2

    Windows

    Clone in PowerShell:

    git clone --branch v0.1.0-alpha.2 https://github.com/hellobpdu/deep32.git; cd deep32

    Then check the signature from the same folder in Git Bash, which comes with Git for Windows and includes GnuPG:

    gpg --import install/release-key.asc
    git verify-tag v0.1.0-alpha.2
  2. The signing key's fingerprint must be B205 B406 5486 27AA BF52  50D8 A078 C5F2 5D02 5DD6, as printed in the README.
  3. Use the scripts from this verified clone for every step that follows.

Let your agent do the next steps

If Claude Code or Codex runs on this PC, open it in the clone and run /deep32-install in Claude Code or $deep32-install in Codex. It follows AGENTS.md and asks before it changes anything. Passwords, sign-in clicks and pairing codes stay yours.

What you should see

git verify-tag reports a good signature made by the key with the fingerprint above.

If it doesn't

  • No public key: run the gpg --import line first, from inside the clone.
  • A bad signature: don't use that clone. Delete it and clone again. If the check still fails, report it as SECURITY.md describes.

Step 3: Run the wizard

Where: the PC, in the cloneDownloads 21.5 GB

What you need

  • The verified clone from step 2.
  • bash 4.2 or newer on Linux; Windows PowerShell 5.1 or PowerShell 7 on Windows.
  • A terminal window of at least 80 columns by 24 rows.
  • On Windows, PowerShell started as administrator, with Docker Desktop running: the Forge install in step 7 loads Docker images and adds a startup task.

Do this

  1. Optional: watch the whole wizard first against a recorded setup. It uses no network and changes nothing.

    Linux

    bash install/deep32-wizard.sh --demo

    Windows

    powershell -NoProfile -ExecutionPolicy Bypass -File install\deep32-wizard.ps1 -Demo
  2. Start the wizard:

    Linux

    bash install/deep32-wizard.sh

    Windows

    powershell -NoProfile -ExecutionPolicy Bypass -File install\deep32-wizard.ps1
  3. Check this machine. The wizard checks the PC and lists anything that's missing. It offers to fix what it safely can, such as starting the Tailscale sign-in, and asks before it does.
  4. Your machines. Set the Workstation, the Forge and the Agent PC to Set it up on this machine, then choose Continue.
  5. Choose role. The wizard starts with the Workstation host. It downloads and verifies disc 1 and disc 2, writes the VM files, and then opens the VM guide (step 4).

Keys: arrows choose, Enter continues, Esc goes back, L shows the log, ? shows help, Q quits.

What you should see

  • A rail on the left with the stages Check this machine, Choose role, Download and verify, Install, Pair and Done.
  • The download progress of each image. deep32-get keeps an image only if every check against the release's signed metadata passes.
  • For the Workstation host, the Install stage ends with Disc 1 checked again and VM files and commands written.

The wizard keeps a log of every run in ~/.local/state/deep32-setup on Linux and %LOCALAPPDATA%\Deep32-setup on Windows.

If it doesn't

  • Make the window bigger: the window is smaller than 80 by 24. Resize it, or press P to go on in plain text.
  • A step fails: the wizard shows an error code, what happened and the fix, with Try again, Back and Show the log. Troubleshooting by error code explains where the codes come from.
  • A download stopped: run the wizard again. deep32-get resumes from the last verified 64 MiB chunk. If every mirror fails, it prints the image's torrent address; the advanced guide shows how to check a file you fetched that way.
  • When the input or output isn't a terminal, TERM is dumb or NO_COLOR is set, the wizard prints the setup script's tagged lines in place of its screens. --plain (-Plain) does the same on purpose.

Step 4: The Workstation VM

Where: the PC and its hypervisorThe guided install takes about 15 minutes

What you need

  • The VM files from step 3: deep32-get's recipe for Hyper-V or KVM, next to the verified disc 1 in the download folder.
  • Hyper-V on Windows, or KVM with libvirt on Linux.
  • These settings for the VM. The guide gives every value for your hypervisor.
SettingValue
FirmwareBIOS (legacy). On Hyper-V, a Generation 1 VM: OpenBSD doesn't support Generation 2
Processors, memory6 vCPUs and 12 GB; at least 4 vCPUs and 8 GB
First diskDisc 1, the installer. It is a disk image: attach it as the VM's first disk and boot from it
Second diskEmpty, 200 GB or more. The guided layout sizes the Library partition from it
NetworkOne adapter, bridged or NAT, with DHCP and internet access. On KVM, e1000
DisplayStandard VGA. The desktop hasn't been tested on virtio-gpu
Disc 2Later (step 6): a virtual CD, a USB stick or the network

Do this

  1. When the Workstation host role is done, the wizard opens the VM guide. Pick your hypervisor; the one found on this PC is preselected. Proxmox VE is marked boot-tested; the others say not boot-tested yet.
  2. Where does the VM run? Choose On this PC.
  3. How the Workstation VM connects. Bridged is recommended: the Workstation gets an address on your LAN, and Tailscale usually connects directly between machines on the same LAN. NAT also works. Host-only, internal and private networks don't, because the Workstation's Tailscale sign-in needs the internet.
  4. Work through the guide's steps. Each one says what to do and where, with every value filled in. Press Enter and the wizard checks it: OK, an ERROR with its code and fix, or YOU CONFIRMED for a step it can't see. Its Create the VM step uses deep32-get's commands with the target disk at 200 GB; the commands.txt file in the VM folder still says 160 GB.
  5. Install the Workstation. Start the VM and open its console. The guided installer asks for the keyboard layout, the machine name, whether to allow root maintenance over SSH with your own key (off unless you choose it), your user name, the disk to install on, whether to encrypt it, and your time zone. Enter accepts a default. For the machine name, type the Workstation name you gave the wizard. Install to the empty 200 GB disk, never to the installer disk; you confirm it by typing its name, because the whole disk is erased.
  6. The install takes about 15 minutes and halts with The operating system has halted. Please press any key to reboot. Don't press a key: with disc 1 still first in the boot order, that starts the installer again. Turn the VM off instead.
  7. Boot the installed disk; attach disc 2. Detach the installer disk. If disc 2 goes in as a virtual CD, attach it now; a USB stick or the network comes in step 6. Then go on to step 5.
The commands the guide gives for Hyper-V and KVM

The guide fills in your names. Deep32Workstation is the VM name in deep32-get's recipe; SWITCH is your External switch (bridged) or an Internal switch with NAT, which Get-VMSwitch lists; DISC2 is the path of disc 2 in your download folder.

Windows (Hyper-V)

Create the VM, in PowerShell as administrator, in the VM folder:

$root = (Get-Location).Path
New-VHD -Path (Join-Path $root 'target.vhdx') -Dynamic -SizeBytes 200GB
New-VM -Name Deep32Workstation -Generation 1 -MemoryStartupBytes 12GB -NoVHD -SwitchName 'SWITCH'
Set-VMProcessor -VMName Deep32Workstation -Count 6
Add-VMHardDiskDrive -VMName Deep32Workstation -ControllerType IDE -ControllerNumber 0 -ControllerLocation 0 -Path (Join-Path $root 'installer.vhd')
Add-VMHardDiskDrive -VMName Deep32Workstation -ControllerType IDE -ControllerNumber 0 -ControllerLocation 1 -Path (Join-Path $root 'target.vhdx')

After the install, detach the installer and attach disc 2:

Remove-VMHardDiskDrive -VMName Deep32Workstation -ControllerType IDE -ControllerNumber 0 -ControllerLocation 0
Add-VMDvdDrive -VMName Deep32Workstation -Path 'DISC2'

Linux (KVM)

Create the VM, in a shell as root, in the VM folder. Read workstation.xml before you define it:

qemu-img create -f qcow2 target.qcow2 200G
virt-install --name Deep32Workstation --memory 12288 --vcpus 6 --os-variant generic --import --boot hd --disk path=installer.img,format=raw,bus=ide --disk path=target.qcow2,format=qcow2,bus=ide --network network=default,model=e1000 --graphics vnc,listen=127.0.0.1 --video vga --noautoconsole --print-xml > workstation.xml
virsh define workstation.xml
virsh start Deep32Workstation

After the install, detach the installer and attach disc 2:

virsh detach-disk Deep32Workstation hda --config
virsh attach-disk Deep32Workstation "DISC2" hdc --type cdrom --mode readonly --config

What you should see

  • The check after Create the VM reads the VM's settings with Get-VM or virsh and shows OK for each one.
  • At the end of the install, the installer prints Remove the install medium before starting the installed system. and halts.

If it doesn't

  • VM_FIRMWARE_UEFI or VM_GENERATION: the VM boots with UEFI. A Hyper-V Generation 2 VM boots with UEFI only, so remove it and create it again with -Generation 1.
  • VM_DISK_SMALL: the VM's largest disk is under 200 GB. Give it an empty disk of at least 200 GB.
  • VM_DISPLAY_VIRTIO: set the VM's display to standard VGA.
  • NET_HOSTONLY: the VM is on a host-only, internal or private network. Connect it to a bridged or a NAT network.
  • KIT_MISSING: the guide found no verified disc 1 with deep32-get's VM folder. The error shows the deep32-get line that makes it; then start the guide again with --vm-guide (-VmGuide), adding --kit DIR (-Kit FOLDER) for another download folder.
  • The VM started the installer again after the halt: turn it off, then detach disc 1 or move the target disk ahead of it in the boot order.

Step 5: First boot and Tailscale sign-in

Where: the VM's console, then any device with a browser

What you need

The VM set to boot from its installed disk, your Tailscale account, and any device with a browser.

Do this

  1. Start the VM. On its console, set the passwords for your user and for root.
  2. The Workstation makes its own tokens and keys, then starts Tailscale once its network is up. It shows the sign-in address in three places:
    • on the text console (Ctrl+Alt+F1), in a status line with signin=https://login.tailscale.com/a/…;
    • on the VM's serial port, if it has one, every 10 seconds;
    • in the First Start window under Sign-in address. First Start opens by itself when you log in to the desktop.
  3. Open the address on any device and sign in with your account.
  4. In the wizard, the First boot and Tailscale step waits for the Workstation to join your tailnet.
  5. Optional: on the admin console's Machines page, choose Disable key expiry for the Workstation.

What you should see

  • The wizard shows OK when a new machine with the Workstation's name comes online in your tailnet, and the admin console lists it as connected.
  • Until disc 2 is imported, the boot messages list kiwix_serve(failed). That is expected: the encyclopedia server has no library to serve before the import, and the import starts it.

If it doesn't

  • The address expired before you used it: Tailscale makes a new one, and First Start shows it. As root, tailscale status prints it too.
  • TS_NOT_HERE: this PC isn't signed in to your tailnet, so the wizard can't see the Workstation join. Confirm it in the admin console, or sign this PC in and check the step again.
  • TS_PEER_MISSING: no machine with the Workstation's name is online yet. Finish the sign-in with the address on the Workstation's console.
  • The sign-in stalls: the Workstation checks DNSSEC through the DNS server that DHCP gives it, and a few routers' DNS breaks that. Give the VM's network another DNS server.

Step 6: Disc 2, the content

Where: the WorkstationSearch ready in about 8 minutes, the Library in about 2 hours on my lab VM

What you need

  • The Workstation signed in to your tailnet (step 5).
  • Disc 2 (19.6 GB), which the wizard downloaded and verified in step 3.
  • The 200 GB Workstation disk: the import needs about 20 GB free on the Library partition.

Do this

Give the Workstation disc 2 in one of three ways and leave it there. Once the Workstation is signed in, it finds disc 2 and imports it by itself. If you attached disc 2 in the VM guide, the import is already running.

A CD drive or a virtual CD

In a VM, attach disc 2 as a read-only CD/DVD drive. The VM guide's Boot the installed disk; attach disc 2 step has the command for your hypervisor. On a real machine, burn disc 2 to a 25 GB Blu-ray disc (BD-R) for an optical drive.

A USB stick

Write the disc 2 image to a stick of 32 GB or more with balenaEtcher or dd. This erases the stick. Plug it in.

Over the network

On the Workstation, choose Get Disc 2 over the Network in First Start, or run this on the console:

doas /usr/local/d32/sbin/d32-content-fetch

Then pick a source:

  • A PC on your tailnet that has disc 2, normally the one that ran the wizard. On that PC, choose Send disc 2 in the wizard. It shows the PC's tailnet name and a ten-character code. On the Workstation, pick that PC and type the code. Keep the wizard open until the download is done: Enter stops sending, and so does closing the wizard. On Linux, sending needs root, or your user set as the Tailscale operator with sudo tailscale set --operator=$USER.
  • The Internet Archive mirror, chosen on the Workstation. No PC is needed.

The Workstation downloads the image into its empty update slot, carries on after an interruption, shows the progress, and deletes the image when the import is done.

What you should see

  1. The import checks disc 2's signature and the free space, then reads the disc once, in two parts, checking each file's size and SHA-256 against the signed manifest. First Start and the console follow it, and the desktop's Import Report shows each step.
  2. What search needs comes first. When it's in, the console says the knowledge base is ready; the Library is still importing. From then on search, Ask, publication and pairing work, so go on with step 7. On my lab VM (KVM on Proxmox, disc 2 on a virtual CD drive) that was about 8 minutes after sign-in. Over the network, the download comes first.
  3. The Library follows in the background and switches on once it has checked out. The whole import took about 2 hours there. When it's done, tail /var/log/d32-import.log ends with a finish outcome=imported line.

If it doesn't

  • Don't start the import by hand. Only if Import Report shows that the import stopped, press Try Again there, or run it as root on the console, naming the CD drive (dmesg | grep ^cd shows it):
    /usr/local/d32/libexec/d32-content-import --device cd0
    /usr/local/d32/libexec/d32-content-import --report shows the import's progress on the console.
  • IMPORT_SPACE: the Library partition is too small, as on a disk under 200 GB. The knowledge base still goes into use; the Library stops before any of it is copied.
  • IMPORT_KB_ONLY: the Library part failed. The knowledge base stays in use, and Import Report says so.
  • A network download stopped: choose Get Disc 2 over the Network again. It carries on where it stopped.

Step 7: The Forge

Where: the PCDownloads about 37.1 GBOn Windows, PowerShell as administrator

What you need

  • The host. Ubuntu 24.04 on amd64 with Docker Engine, on the host itself or as a WSL 2 distro; or Windows 11 build 26100 or later (Home, Pro, Enterprise or Education) with Docker Desktop 4.99.0 or later and Docker Engine 29.0.0 or later on the WSL 2 backend. The installer stops on any other system.
  • The card. Compute capability 7.5 or newer with at least 10.5 GB of graphics memory, and driver 580.65.06 or newer. On Windows the host driver serves Docker Desktop; don't install a Linux graphics driver inside its WSL 2 backend. On Linux, the NVIDIA Container Toolkit.
  • Docker's classic image store (overlay2). The alpha.2 Forge images load only into it, and Docker Engine 29 and Docker Desktop keep images in containerd by default. Images and containers you keep in the other store stay hidden until you switch back, so the installer never changes this for you. To switch:

    Linux

    Add this key to /etc/docker/daemon.json, then restart Docker:

    "features": {"containerd-snapshotter": false}
    sudo systemctl restart docker

    Windows

    In Docker Desktop, open Settings, General, turn off Use containerd for pulling and storing images, and choose Apply & restart.

  • Python. 3.12 or newer for the installer. On Linux the pairing helper runs on /usr/bin/python3, which must be 3.10 or newer and able to import ssl. sh install/forge-host-python.sh checks it, and sudo sh install/forge-host-python.sh --install installs it with apt, dnf, zypper or pacman.
  • Free space. About 281 to 284 GB when you start, if the data folder and Docker's storage share one filesystem or volume (other layouts).
  • Tailscale. A machine name that starts with deep32-, in the same tailnet as the Workstation (step 1).

Do this

  1. On the wizard's Done screen, choose Set up the Forge here. Or start the wizard again and choose Forge.
  2. The checks run for the Forge: Python, the card and its class, the driver and its memory, Docker, Compose, the classic image store, the Container Toolkit, the pairing helper's Python, and Tailscale.
  3. The wizard downloads and verifies your card's three images from disc 3: the 18.6 GB shared core, your card's 3.1 to 3.3 GB embedder and the 15.3 GB ingestion image.
  4. The installer checks the host before it changes anything. It asks you to confirm the tailnet the Forge will publish on, and to agree that the Forge's name goes into the public Certificate Transparency logs. Then it shows its plan: the folders, the ports, and the size and SHA-256 of each image.
  5. To agree to the plan, type the 64-character digest shown under it (spaces are fine, and pasting works), then choose Install.

What you should see

The install goes through Plan accepted, This host checked again, Images mounted read-only, Forge loader running, Settings handed over and Forge started; its doors answer with a token request. Just before the host check's result, the installer prints a line like this one for Ubuntu 24.04. It doesn't stop the install:

Note: this host type is accepted for 0.1.0-alpha.2 under an owner waiver dated 2026-11-18 (recipe ubuntu-24.04-docker-engine-j2). I have not yet run a full install on it; FORGE-PREREQUISITES.json lists what was not run.

On Windows the recipe is windows-11-docker-desktop-wsl2-j1. The run ends with:

[ok] Forge installed and running
[ok] door answers on https://deep32-forge.YOUR-TAILNET.ts.net:443 and asks for a token
[ok] door answers on https://deep32-forge.YOUR-TAILNET.ts.net:8443 and asks for a token
A terminal running the setup script on a Forge host. Each line starts with a tag: ok for a check that passed, fix for something to correct, you for a step only a person can do, and info for progress. It checks Python, the graphics card, Docker and Tailscale, installs the Forge, checks its door and ends with the pairing code to type on the Workstation.
Figure 2. The same Forge setup in plain mode. Every line starts with a tag, so a person or an agent can follow it.

To check the door yourself: it answers 401, which means it is up and wants a token.

Linux

curl -s -o /dev/null -w '%{http_code}\n' https://deep32-forge.YOUR-TAILNET.ts.net/health

Windows

curl.exe -s -o NUL -w "%{http_code}`n" https://deep32-forge.YOUR-TAILNET.ts.net/health

If it doesn't

  • docker-store-containerd: Docker still uses its containerd store. Switch it as shown above, then run the wizard again.
  • gpu.memory: the card has less memory than the signed plan needs.
  • host.magicdns or host.https-certificates: turn MagicDNS or HTTPS Certificates on in the admin console's DNS page, then run the wizard again.
  • tailscale-approval: the PC waits for approval in your tailnet. Approve it on the admin console's Machines page.
  • Not enough free space: the installer compares free space with the storage budget signed into the release, before it joins the images and again after. The disk table has the figures for each layout.
  • The door answered something other than 401: it may still be starting. Wait a minute and run the wizard again. On the host, tailscale serve status should list the HTTPS routes for ports 443 and 8443.

Step 8: Pair the Forge

Where: the Workstation and the PCA code lasts five minutes

What you need

  • The Workstation's knowledge base in use: Import Report shows it. The Library can still be importing.
  • The Forge's pairing window open. Until it is paired, each start of the Forge opens a five-minute window with a ten-character code, and the wizard's Pair screen shows it.

Do this

  1. On the Workstation, open Pairing and choose Forge. From a terminal on the Workstation:
    doas /usr/local/d32/sbin/d32-pairdesk -forge
  2. Pick your Forge, for example deep32-forge.
  3. Type the code from the wizard's Pair screen. Spaces and the dot between the two groups are fine.
  4. Wait until the Workstation says the pairing is saved, then choose Paired in the wizard.
Reading the code without the wizard

Linux

The code is in a file only root can read:

sudo grep -o 'pair=[A-Z2-7]*' /opt/deep32/status/status

Windows

A small helper opens the pairing window, from an elevated PowerShell in the clone. It keeps the current code in C:\Deep32\status\windows-pair, readable only by you and SYSTEM:

python -I -B src\release-tools\forge_pair_windows.py --data-root C:\Deep32

What you should see

Pairing turns meaning search on by itself, and Pairing lists the Forge as paired. Within a minute the Workstation has checked both of the Forge's models. As root, /usr/local/d32/sbin/d32-gpu-ext status then shows "verified": true for embed and rerank.

If it doesn't

  • The code expired: choose New code (runs the setup again) in the wizard. If the window closes before you pair, the Forge's services keep running but it records itself as stopped until you start it again.
  • After three failed attempts within 30 minutes, pairing locks for 15 minutes.
  • Your Forge isn't in the list: the Workstation only offers machines whose Tailscale name starts with deep32- and that are in its own tailnet. Check tailscale status on both.
  • The models don't show as verified: the wizard's list of next steps turns them on and checks them, from a terminal on the Workstation:
    doas /usr/local/d32/sbin/d32-gpu-ext on
    doas /usr/local/d32/sbin/d32-gpu-ext status

Step 9: Publish the gateway and connect your agent

Where: the Workstation's text console, then the PCA code lasts five minutes

What you need

  • The Workstation's knowledge base in use.
  • Claude Code or Codex installed and signed in on the PC, Python 3.11 or newer for Connect, and OpenSSL on PATH.
  • Tailscale on the PC, signed in to the same tailnet as the Workstation.

Do this

  1. Publish the Workstation's gateway, once, as root on its text console (Ctrl+Alt+F1):
    /usr/local/d32/sbin/d32-publish publish --accept-ct
    With --accept-ct you agree that the Workstation's HTTPS name, <workstation>.<tailnet>.ts.net, is recorded in the public Certificate Transparency logs, as every Tailscale HTTPS name is. Without it, publication stays off. The command checks the gateway and ends with the Connect command for this Workstation, for Linux and for Windows.
  2. On the PC, choose Set up the Agent PC here on the wizard's Done screen, or start the wizard again and choose Agent PC. Give it the Workstation's address and your agent, then choose Start Connect. By hand, from the clone, with claude for Claude Code or codex for Codex:

    Linux

    bash adapters/connect.sh --agent claude --workstation 'https://<workstation>.<tailnet>.ts.net/mcp'

    Windows

    powershell -NoProfile -ExecutionPolicy Bypass -File adapters\connect.ps1 -Agent claude -Workstation 'https://<workstation>.<tailnet>.ts.net/mcp'
    Connect checks the published gateway, then waits at Workstation one-time code for claude (hidden, 10 characters):.
  3. On the Workstation, open Pairing and choose Headend, or run /usr/local/d32/sbin/d32-pairdesk -headend as root on the console. It shows a ten-character code that lasts five minutes. Type it at Connect's prompt, which shows a dot for each character. On the console, press Enter afterwards to close the pairing screen.
  4. If the agent already has a configuration on the PC, Connect lists the files it will back up and merge, and asks Type merge to approve this file plan:. Type merge to go on. If you decline, Connect stops without changing those files.
  5. Start the agent with the Launch: command Connect prints. When it asks, approve only the eleven Deep32 tools, then run the skill's check: /deep32 first-session check in Claude Code or $deep32 first-session check in Codex.

What you should see

Run the Connect command again with --check (-Check in PowerShell). It changes nothing and ends with:

claude: read-only authentication and eleven-tool checks passed; client version …

Connect also installs the research skills: deep32 for Claude Code, and for Codex deep32, deep32-configure, deep32-describe, deep32-design, deep32-troubleshoot and deep32-verify. From now on the same agent answers from your Workstation through them. Connect installs them under a scoped name, such as deep32_1a2b3c4d; Agent Adapters section 6 has the details. In the first session, rag_status reports keyword search, embeddings and reranking as healthy.

If it doesn't

  • 401 from the gateway: start the agent with the printed launcher. If it still fails, revoke the headend on the Workstation and pair again.
  • Name not found: check tailscale status on the PC and the address the Workstation shows.
  • Timeout: check publication on the Workstation, then run Connect with --check.
  • expired: the code or its window expired. Choose Headend again on the Workstation for a new code, and type it within five minutes.
  • unreachable: the PC couldn't reach the Workstation's pairing service. Check that Tailscale on the PC is in the Workstation's tailnet and that the Headend pairing window is open.
  • dense or reranker in degraded: the Forge is off or unreachable; keyword search still works.
  • agent-credential-mode-unsupported: update Claude Code. Connect never falls back to writing the token into a file.

Step 10: The Ask relay (optional)

Where: the PC and the Workstation's text console

The relay lets you type a question in the Workstation's Ask window and have the agent on the PC answer it. In this release Ask answers through the relay with Claude Code, with the model and strength you choose.

Who can use Ask

Ask has no password of its own in this release. Anyone with an account in the Workstation's _d32users group, which includes the desktop user the installer creates, can open Ask and ask on the plan of the agent signed in on the PC.

What you need

  • The gateway published (step 9).
  • The PC's Tailscale name starting with deep32-, in the Workstation's tailnet (step 1).
  • On Linux, your user allowed to manage Tailscale Serve, once: sudo tailscale set --operator=$USER.

Do this

  1. Install the relay for your agent. It prints the relay's install ID; put it in place of <id> below.

    Linux

    bash adapters/connect.sh --relay install --agent claude --relay-transport tailnet --tailscale-binary "$(command -v tailscale)"

    Windows

    powershell -NoProfile -ExecutionPolicy Bypass -File adapters\connect.ps1 -Relay install -Agent claude -RelayTransport tailnet -TailscaleBinary "C:\Program Files\Tailscale\tailscale.exe"
  2. Sign the relay's own agent profile in. The relay runs the agent in a separate profile with none of your settings, so it needs its own sign-in:

    Linux

    bash adapters/connect.sh --relay login --relay-id '<id>' --agent claude

    Windows

    powershell -NoProfile -ExecutionPolicy Bypass -File adapters\connect.ps1 -Relay login -RelayId '<id>' -Agent claude
  3. On Linux, once, let the relay run while you're logged out: sudo loginctl enable-linger $USER.
  4. Open pairing on the PC. On Linux, stop the relay's service first:

    Linux

    systemctl --user stop 'deep32-relay-<id>'
    bash adapters/connect.sh --relay pair --relay-id '<id>' --agent claude

    Windows

    powershell -NoProfile -ExecutionPolicy Bypass -File adapters\connect.ps1 -Relay pair -RelayId '<id>' -Agent claude
  5. While pairing is open, run /usr/local/d32/sbin/d32-pairdesk -relay as root on the Workstation's text console (Ctrl+Alt+F1) and pick the PC. Each screen shows ten words. Type the Workstation's words on the PC and the PC's words on the Workstation. The comparison runs only on the text console. It doesn't run in a terminal window on the desktop.
  6. On Linux, start the service again: systemctl --user start 'deep32-relay-<id>'. Keep publication on while you use Ask.

What you should see

--relay status (-Relay status) reports the relay ready. A question you already know the answer to streams into the Ask window, and its research line lists the searches the agent made.

If it doesn't

  • A typing slip at word 3 of 10: is asked for again. A different pairing word means the two screens disagree, so pairing stops and nothing is stored.
  • To pair a different relay, remove the old one on the Workstation first: /usr/local/d32/sbin/d32-chatctl unpair work.
  • agent-sign-in-required: the relay's agent profile is signed out. Sign it in again (item 2).
  • A turn ends with agent-start-failed: use your agent directly through Connect, and see the known issues in the release notes.
  • Ask stopped working after you unpublished the gateway: publish it again.

Agent Adapters section 5 has the relay in full, with the model and strength menus and how to remove it.

Step 11: Verify

Where: the Workstation and the PC

What you need

Steps 1 to 9 done. Step 10 is optional.

Do this

  1. On the Workstation, Pairing lists the Forge as paired, and a search there ranks by meaning: a question in plain words finds the right RFC section even when it shares no keywords with it.
  2. Ask your agent something you already know, such as the BGP hold time in RFC 4271. Check that it cites the RFC and quotes it.
  3. Later, at any time, the setup's check reports the state of a machine and changes nothing:

    Linux

    bash install/deep32-setup.sh check

    Windows

    powershell -NoProfile -ExecutionPolicy Bypass -File install\deep32-setup.ps1 check

What you should see

RFC 4271 suggests a 90-second hold time, with keepalives at a third of that. 60 and 180 seconds are the Cisco IOS and IOS XE defaults. A good answer gives the two separately and quotes both sources.

End of an Ask answer about BGP timers: the reason BGP uses its own keepalives, the 3:1 ratio marked as inference, Cisco 60/180 against the RFC's suggested 90-second hold time, the research line with 15 RAG calls, and four RFC 4271 source links.
Figure 3. The BGP timer question in the Ask window. Cisco and RFC values are given separately, and the 3:1 ratio is marked as inference.

If it doesn't

  • rag_status shows embeddings or reranking as degraded: the Forge isn't reachable, and searches fall back to keyword matching until it is. Go back to step 8.
  • deep32 doctor and deep32 selftest are on the images, but in 0.1.0-alpha.2 doctor can't read the install record and selftest has no signed reference values, so neither gives a useful result yet. Fixes for both are planned for 0.1.0-alpha.3.

That's the install

Starting, stopping, upgrading and removing the parts are in the advanced guide. Optional features that would contact anything ship off; Optional Features lists each one and what it would contact. If something here didn't match what you saw, please open an issue.