Set Up a Box

If there's an NVIDIA card, install its driver and the CUDA toolkit yourself before step 4. LocalGhost installs neither. Setup builds the model engine for the card the driver reports, and for the CPU when it finds no nvcc under /usr/local/cuda*/bin or no card the driver can see. Run the steps as your own login user, the one with sudo. That user becomes the service user, which installs and deploys, and the daemons run as a separate user that can't log in.

# the site key's signature over the APK
curl -LO $R/localghost-app-0.0.5.apk.asc
curl -s https://www.localghost.ai/.well-known/pgp-key.asc | gpg --import
gpg --verify localghost-app-0.0.5.apk.asc localghost-app-0.0.5.apk

# the certificate it's signed with, apksigner is in the SDK build-tools
apksigner verify --print-certs localghost-app-0.0.5.apk

# the key gpg must name, and the certificate apksigner must print
DCE9 A3D1 4EB4 6197 1DD5 F393 706E 4194 F08A 09A0
3dcc5e35718036a26cf36373ee53e79f512bf02d97f7017052996d55ddf0cdf4

gpg should report a good signature from info@localghost.ai with the first, and apksigner a signer certificate whose SHA-256 digest is the second. Android installs an update over the app only when it's signed with that same certificate, so a copy signed by anyone else can't replace it quietly. In the app, VERIFY BUILD shows the release ("wisp 0.0.5 (5)"), the commit it was built from (b5ef714), the source manifest's root and the signing certificate, and APP.txt in the release states the same hash, commit and certificate. The APK isn't byte-reproducible yet (a Gradle build differs from run to run), so the signed copy in the release is the one to check, and app/android/VERIFY.md says how. 0.0.5 installs over any earlier wisp and keeps the enrolment, since the key is the same.^[4] The same APK is in the mirror's app set, so a USB copy of the mirror can set up the phone as well as the box.

On Windows install Android Studio (it brings JDK 21) and in its SDK Manager tick Android API 37 and 36, Build-Tools 36.0.0, NDK 28.2.13676358 and CMake 3.22.1, the versions the build pins. Put the repo in a path without spaces, turn on USB debugging on the phone, plug it in and run gradlew.bat installDebug in app\android. On Debian, one script installs the same toolchain.^[3]

app/android/tools/debian_setup.sh
source ~/.localghost_android_env
adb devices                          # the phone should be listed
cd app/android && ./gradlew installDebug

The build fetches the llama.cpp source for the phone's own model from the setup mirror and refuses it unless its SHA-256 matches the pin in app/src/main/cpp/CMakeLists.txt. With no internet, put llamaTarball=<path> in local.properties. Open MODELS in the app to check, and the top line should say "runtime in this build (llama.cpp v0.5.0-…)". A build of your own is signed with your own key, so Android won't put it over the released app or the released app over it, and uninstalling one to install the other loses the phone's enrolment. Pick one before you scan the QR.

The sums name each file under the release's folders (server/, app/, source/), and GitHub serves them flat, so the sed drops the folder and the names match what curl saved. Without it, sha256sum finds none of the files and says so. The setup mirror's server set carries the same bundle under a manifest signed by the same key.

M=https://www.localghost.ai/mirror
curl -sO $M/MANIFEST.txt
curl -sO $M/MANIFEST.txt.asc
gpg --verify MANIFEST.txt.asc MANIFEST.txt
BUILD=$(sed -n 's/^# Build: //p' MANIFEST.txt)
curl -sO $M/$BUILD/server/localghost-server-$V-linux-amd64.tar.gz
grep " /$BUILD/server/localghost-server-$V-linux-amd64.tar.gz$" MANIFEST.txt | sed "s# /$BUILD/server/# #" | sha256sum -c

install.sh copies the release to /opt/localghost/release/0.0.5/, the operator scripts to /opt/localghost/tools/ and ghost-cli, ghost-ctl and ghost-qr to /opt/localghost/bin/, the same places a release taken from the phone puts them, then runs setup.sh from the release, which sees the binaries and builds none of them.

1. Packages. Postgres 18 with pgvector and Redis 8 from their own apt repositories, then cryptsetup and tpm2-tools. It loads dm_crypt, lets your user reach the TPM through the tss group, adds a narrow sudo rule for managing the ghost.secd unit, and writes /etc/ghost/ghost.env. On a machine that had no database before, the Postgres and Redis services the packages start on their own are masked, because the box runs private instances inside the encrypted volume, on their own ports. Databases the machine already runs for other things are left alone.
2. Checks. As your user, in a fresh login so the new group counts, it confirms that the packages, the TPM, the state folder and the sudo rule all work for you.
3. The engine and the models. llama.cpp built from the mirror's pinned source for the compute capability the driver reports (nvidia-smi, one card or several), or for the CPU, said loudly, when there's none. GHOST_CUDA_ARCHS=89 names it by hand. Then Gemma 4 12B with its vision projector, the EmbeddingGemma embedder, the phone's model and the speech engine, each checked against its pin and staged for the first unlock. GHOST_LLAMA=0 leaves them for update.sh engine later.
4. Volume. It lists the disks and the mounted drives, and you give it a whole empty disk or a path for a file. Name a disk by its /dev/disk/by-id/ name, since names like nvme0n1 can swap between boots.^[8] It shows the model, size and serial number, or the file, its size and the drive it's on, and asks you to type YES, plus WIPEIT if the disk or file already holds a LUKS container and IUNDERSTAND if anything on a disk is mounted.
5. Seal and name. The seal tier, tpm for a real box or software for a machine without one, and the domain, left blank for the home network only.
6. Provision. It creates ghostd, the user the daemons run as (no password, no shell), runs ghost-setup as a dry run that touches nothing, and asks you to type APPLY. The apply asks for the main PIN and the wipe PIN on the terminal, formats the volume, sets up its databases and copies their runtime onto it, makes the box its own certificate authority, writes the nginx site and the systemd unit, starts ghost.secd and draws the QR.

The volume is one LUKS2 container, and cryptsetup opens a file as readily as a disk, attaching a loop device of its own. Give the volume step a path on a drive that's mounted at boot and a size (20 GB at least, 500G or 1.5T say). The file is allocated in full with fallocate, with copy-on-write turned off first on btrfs, and the ghost.secd unit waits for that drive to be mounted. If the drive isn't there at unlock, secd says so rather than searching the disks. The seal, the PINs and the wipe work as they do on a disk. The file is ciphertext, a copy of it is ciphertext, and there's no key outside the seal. The drive shows a file of a size and a date, the way a disk shows its size. Don't put it on a network share. By hand it's ghost-setup --image /mnt/data/localghost.img --size 500G.^[15]

A box that builds its own code is set up from a clone, and setup.sh builds first, with Go 1.27.1 from the mirror (tools/install_go.sh) when the machine's Go is older than go.mod asks for. Everything else is the same, and redeploy.sh later builds and installs from the tree.

# as root
apt install git make

# as your login user, the release, or main for the newest code
git clone --branch v0.0.5 https://github.com/LocalGhostDao/localghost.git
cd localghost/server
sudo ./tools/setup.sh $USER

Scanning is the enrolment, with no code to type, no confirmation and no network call. The code is 858 bytes split over twelve frames, the phone's certificate and private key, the box's address, its name and the fingerprint of its server certificate, and any eight frames rebuild it, so a clean scan takes 8 to 12 seconds.^[6] The box stops showing frames after the first verified connection. Until the first unlock anyone with a recording of those frames holds a working device identity (they'd still need the PIN). At the first unlock the phone makes a key of its own in its hardware keystore, the box signs a new certificate for it and retires the one the QR carried, so a recording is worthless from then on. If the terminal is too small to draw the code, setup says so instead of printing it any other way, and ghost-qr draws it once the window is bigger.

The app trusts the box by that fingerprint, not by its name. If the box sits behind a router without NAT hairpinning, the domain won't reach the box from inside your own network, so use the LAN address as the host and keep the domain for outside. Enrolment doesn't need the domain at all, and you can leave it blank at setup and add it later.

update.sh fetches only what differs from the signed list. English Wikipedia is one file of about 50 GB, and the box imports it into its own database in the background, an hour or two, with Box Status showing how far. Once the articles are in, the file is removed, and the chat's "what is …", the coin pages and the WIKIPEDIA page in the app read them on the box. GHOST_WIKI=0 leaves it out. Streets are opt-in because they're big. Africa takes about four minutes to cut and Europe takes hours. If the model turns out to be on the CPU when you expected the GPU, sudo /opt/localghost/tools/gpu.sh says which layer failed. Box Status shows each pipeline stage as done, total and pace.

Once a day on Wi-Fi the app reads the mirror's signed list. DEPLOY downloads the release and hands it to the box, which checks the signature and every hash with the same verifier setup used, keeps the previous build and switches to the new one. It goes back by itself if the first unlock onto the new build fails or a critical daemon keeps falling over in its first ten minutes. SETTINGS › SERVER names the build the box runs, its commit, when it was built and with which Go.

# a box set up from a checkout: code from git, built and installed,
# secd restarts, so the box locks
git pull && sudo ./tools/redeploy.sh

# a shell inside the namespace, standing on the volume
sudo /opt/localghost/tools/ns.sh

# the box's privacy settings, encrypted swap included
sudo /opt/localghost/tools/privacy_check.sh

A redeploy restarts ghost.secd, which locks the box, and you unlock again from the phone. New daemon binaries wait in a staging folder on the system disk and move onto the volume at that unlock. Arm the watchdog on any box you can't walk up to. Mine froze once while I was away and stayed frozen until someone could press the button.^[6]