System & data

Health checks

aios doctor            # diagnose the setup (kernel, runtime, models, GPS, data schema, …)
aios doctor --fix      # offer to repair: build the kernel, create the venv, pull a model

The dashboard System tab shows the same machine awareness — CPU/RAM/GPU, services, disks — plus the data controls below.

GPU acceleration

The model runtime picks the fastest backend for your hardware automatically — nothing to configure:

• NVIDIA → CUDA (bundled).
• AMD or Intel GPU (including integrated graphics / APUs like a Radeon 760M) → Vulkan, via the baked Mesa driver. Detected at startup — a real GPU is used; a software rasteriser is not.
• No usable GPU → optimised CPU inference.

aios doctor shows the chosen backend on the acceleration row (e.g. Vulkan (AMD/Intel GPU) · AMD Radeon Graphics), and the System tab shows an Acceleration card. An integrated GPU shares system RAM rather than having its own VRAM, so the model size is chosen from your RAM (as on a CPU-only box) and the GPU then accelerates whatever fits. Confirm the runtime is really using the GPU with vulkaninfo --summary (should list your GPU, not just llvmpipe) and ollama ps (the PROCESSOR column reads GPU).

Three ways to run ApocOS

There are three situations, and they differ only in where your data lives:

1. Live USB, in memory — booted from the USB stick with no data drive. Everything runs, but it’s all in RAM: any change is lost on reboot, and you can’t permanently add corpora, regions or models. Good for a demo or a one-off.
2. Live USB + a data drive — booted from the USB, but with a persistent AIOS_DATA drive attached. The OS still runs read-only from the stick, but your graph, bookmarks, field marks and any corpora, regions or models you add are saved to the data drive and survive reboots.
3. Installed — a full read-write system on the machine’s own disk (aios install). Everything persists; the OS itself is updatable.

On the desktop edition, every live boot opens a short welcome notice first, which tells you which of (1) or (2) you are in — whether your work is being saved, or kept in RAM and lost on reboot. Installed systems (including ApocOS Drive) boot straight to the dashboard. Continue goes to the dashboard as usual; Install to disk… (reach (3)) opens the installer in a terminal window — described below. To go from (1) to (2), set up a data drive from Settings → Data in the dashboard (or aios data init), also below; it takes effect at the next boot, when the resolver adopts the drive.

The installer opens in its own window. On some machines it appears behind the full-screen dashboard — check the taskbar or press Alt-Tab. If no window appears at all, the notice says why; you can always open Terminal (Applications → System) and run sudo aios install yourself.

Where your data lives

On a live boot, your data persists onto a disk labelled AIOS_DATA. Manage it with:

aios data status       # where AIOS_VAR currently resolves (pinned / labelled disk / ephemeral)
aios data disks        # candidate disks
aios data init <dev>   # format a disk as the AIOS data disk (explicit, never automatic — ERASES it)
aios data use <dev>    # choose an existing AIOS data disk: mount it now + pin it (also re-enables one)
aios data pin <dev|uuid> / aios data unpin    # remember (or forget) a disk across boots
aios data eject        # stop using the data disk (see below)

use vs pin. use is pin plus a mount — it writes the same pinned UUID, replacing any existing pin, so it doesn’t merely allow the disk, it chooses it. pin alone records the UUID and changes nothing now. Neither switches the running session: every process keeps the AIOS_VAR that was resolved at boot, so the disk becomes your live store at the next reboot. (Three things decide that boot, in order: a pinned UUID, then any disk labelled AIOS_DATA, then RAM.) So if you accept the EULA, save a bookmark or set Home before rebooting onto a newly set-up drive, that work was written to the old store — redo it once after the reboot.

In the dashboard this is a single Use this drive button (Settings → Data), which tells you it takes effect at the next reboot and offers to restart there and then. pin on its own is a command-line tool for the two cases that need it: two AIOS_DATA disks attached at once (without a pin the resolver takes whichever sorts first, which can change with how an enclosure enumerates), and installed systems, where detection by label is deliberately off — an installed AIOS never adopts a stray disk, so the pin aios install writes when it adopts your data drive is the only thing that selects one.

Ejecting / disabling a data disk is non-destructive. A live boot auto-adopts any disk labelled AIOS_DATA on every boot, so to stop that, aios data eject relabels the disk (AIOS_DATA → AIOS_DATA_OFF) rather than just unmounting it — the next boot no longer adopts it, and your data is completely untouched (only the filesystem label changes; it’s not reformatted). The current session keeps running until you reboot. To use the disk again, aios data use <dev> (or Re-enable in Settings → Data) relabels it back — again without touching the data. Only aios data init ever erases a disk.

Safety: a disk is never formatted without an explicit init; a corrupt or cross-version disk is surfaced loudly, never silently reinitialised. Model pulls persist to the disk too, while baked models stay visible.

A data drive can’t silently brick a machine. Disk management only works from the live USB, and it refuses the running system’s disks. But when you boot the live USB, a machine’s own installed OS isn’t running, so its partitions look idle — so before formatting, AIOS checks whether the target is an EFI boot partition, sits on a disk that has one (an installed OS that would then no longer boot), or just isn’t empty, and warns loudly. In the dashboard those targets are flagged ”⚠ may hold an OS / data” and require you to type ERASE (not just click) — and the installer runs the same OS check before it wipes a disk (see below). Blank disks are the intended, low-friction target.

Installing to disk

aios install                 # install the running live system onto a disk (from the live USB)
aios install --dry-run       # preview the plan without touching any disk
aios install --adopt         # losslessly adopt an existing AIOS_DATA disk (default if present)
aios install --encrypt       # LUKS-encrypt the disk at rest (you set a passphrase)
aios install --seal          # TPM auto-unlock + anti-clone (implies --encrypt); boots hands-off on THIS box
aios install --pull-models   # if a network is present, pull the hardware-fitted model in (non-interactive)

Before it erases anything, the installer checks whether the disk you chose holds an operating system (an EFI boot partition, or a disk that has one). If it does, it warns loudly that installing will permanently destroy that OS and everything on the disk, and — unlike a blank disk’s ERASE — it makes you type the disk’s full path (e.g. /dev/nvme0n1) to confirm, so a booted-from-USB install can’t wipe the machine’s own OS by a mistyped keystroke. Blank disks stay a simple ERASE.

Keeping an existing OS (Windows/Linux). A full install always takes the whole disk you pick — it does not shrink Windows or share a disk with another OS. To keep what you have, install onto a separate empty disk: only that disk is erased, your other drive is left untouched, and you choose which system to boot from your computer’s firmware boot menu (often F12) or by setting the UEFI boot order. If you don’t want to install at all, the live USB itself changes nothing on the machine — just run from it.

--seal (TPM auto-unlock, anti-clone). On a machine with a TPM, --seal binds the encryption key to that box’s TPM, so the system auto-unlocks at boot with no passphrase typed — yet the disk stays useless if cloned to different hardware (the other machine’s TPM can’t produce the key). The passphrase you set with --encrypt becomes the recovery key (kept safe for the rare re-provision). No Secure Boot is required, so ordinary firmware and kernel updates don’t disturb it. This is how a sealed appliance ships: hands-off boot for the owner, but not trivially copyable. (At-rest protection only — someone with the running, unlocked box can still read it.) You don’t have to know the flag: an interactive install offers to seal whenever you choose encryption on a machine that has a TPM. And when you install from the dashboard “Install to disk” button on a machine with a TPM, encrypt + seal is the recommended default (press Enter) — so a self-installed unit auto-unlocks on that machine yet a cloned disk can’t boot elsewhere. A machine without a TPM falls back to the ordinary encryption offer, so it is never saddled with a boot passphrase against your wishes.

The desktop appliance never locks the screen. It autologins (no boot password), so a session lock would only be a password gate to forget — and it adds no real security, since at-rest protection is the encryption above, not a lock on a powered-on box. The screen still blanks when idle to save power; it just never asks for a password to wake.

A sealed box may briefly show Please unlock disk aios_root: at boot, then continue on its own after a second or two — no password is needed. That’s the normal unlock prompt being displayed while the TPM releases the key in the background; when it does, boot proceeds automatically. (The pause is usually shorter on real hardware than in a VM, whose emulated TPM is slower.) The same prompt waits for real only when the TPM can’t unlock — a cloned disk, or a genuine recovery — in which case you type the recovery passphrase.

Re-sealing — aios seal. If the box’s TPM changes — a mainboard or TPM swap, a BIOS “clear TPM”, or you move the disk to different hardware — it stops auto-unlocking and falls back to the passphrase at boot (it’s degraded, not dead). Boot it with the passphrase, then on the installed system run:

aios seal          # re-bind the encrypted root to THIS machine's TPM (needs the passphrase)

Enter the passphrase once to authorise, and it re-binds the key to the current TPM so hands-off boot returns. Because it requires the passphrase, only the owner can do this — a stolen disk still can’t be re-sealed to someone else’s hardware. aios seal also performs the first seal of a box installed with --encrypt but not --seal.

Every sold unit carries a signed serial (aios watermark). Each unit is stamped at imaging time with a per-unit serial, cryptographically signed so it can’t be forged. It’s for traceability, not copy-protection: if a copy of a unit’s software turns up in the wild, the serial identifies which unit it came from. It holds no personal data, and the system never depends on it — it just surfaces in aios doctor and the System tab for support. See your unit’s serial with:

aios watermark show          # this unit's serial + edition
aios watermark verify        # check the signature against the baked key

(Owner-only, at provisioning: aios watermark keygen makes the signing key once. When installing a box, aios install --wm-key <private-key> [--serial S] stamps the unit automatically as part of the install; or stamp any unit standalone with aios watermark stamp --key <private-key>. The private key never ships on a unit. Sticks are watermarked by the stick provisioning flow, not by stamping the running live system — a live stick’s writes don’t persist.)

Stick binding (aios unit). A sold live-USB stick can additionally be bound to its own USB hardware, so a straight dd-copy onto a different stick is detectable. The owner images + binds a stick with iso/provision-stick.sh (it writes the master image, adds a small AIOS_UNIT partition, and signs a record tying the stick to its USB controller serial). At boot the stick checks that binding; a provably cloned stick (one whose USB serial doesn’t match its record) still boots and runs (it’s never bricked), shows a soft-warning in aios doctor and the dashboard, and — the one restriction — cannot install to a hard drive (a copied stick can’t be used to spin up boxes). A genuine stick whose serial simply can’t be read on some machine is treated as indeterminate and is never blocked. An un-provisioned stick has no binding and just works — that’s the master/skeleton image, and it installs freely. See the state with aios unit. Binding is live-USB only: an installed box has no USB serial and relies on TPM sealing instead.

Updates are manual, by design. The system does not auto-update: the apt-daily timers are masked and APT::Periodic is off, so nothing upgrades in the background (an unattended system-Python or Ollama bump could break the pinned runtime). A unit is a point-in-time snapshot — you refresh it by re-imaging with a newer build, not by an in-place upgrade. Manual apt update / apt upgrade still work if you deliberately run them; only the automatic path is disabled.

Installing erases the target and requires typing ERASE to confirm.

Run interactively, aios install guides you through the choices: it lists the eligible disks and lets you pick one (when there’s more than one), offers to encrypt the disk (see below), offers to set a password for the aios account (otherwise it stays the image default aios), and offers to adopt an existing AIOS_DATA disk. The flags above pre-answer any of these for a scripted (--yes) install.

Fitting a bigger model at install time. The baked model is a floor sized to boot on anything. If a network happens to be present when you install, the installer offers to pull the model that best fits this machine (from the same hardware ladder aios model pull uses) straight into the new system, so a capable box boots with the right model — no later manual pull. This is strictly opt-in and never delays or risks the install: offline (the usual field case) it does nothing, and a failed pull just leaves the baked model in place. --pull-models opts in for a scripted install; otherwise it’s a simple prompt. You can always do it later on the installed box with aios model pull assistant / coder once online.

Install onto one disk, keep your data drive. A common field setup is USB + a separate data HDD. When you install the OS onto a target disk, the installer detects any other AIOS_DATA drive and offers to adopt it losslessly — the data drive is never touched; its UUID is pinned so the installed system mounts it as your data store at boot. So you keep everything you’ve collected while moving the OS onto an internal disk. On the desktop edition you can start all this from the live-USB welcome page’s Install to disk button, which opens the installer in a terminal.

Encryption at rest (--encrypt)

--encrypt LUKS2-encrypts the installed system’s root filesystem, so if the machine is lost, stolen, or seized while powered off its data (your graph, chat history, knowledge, pulled models, fetched regions, config) can’t be read without your passphrase. The layout becomes ESP + a plaintext /boot + an encrypted root, so only the boot prompt — not GRUB — asks for the passphrase.

You set the passphrase during install (prompted after the ERASE confirm, before anything is written). Know the trade-offs:

• You type the passphrase at every boot. There’s no TPM auto-unlock, so an encrypted machine cannot start unattended — the autologin desktop/kiosk and headless auto-serve both wait at the passphrase prompt until someone types it at the console.
• A lost passphrase means the data is unrecoverable — there’s no recovery key or escrow.
• Only the OS disk is encrypted. An adopted AIOS_DATA disk is mounted as-is (unencrypted) — a separate encrypted data disk is a planned follow-up.
• Encryption protects data at rest only — a running, unlocked system is not protected.

Non-interactive (--encrypt --yes): pipe the passphrase on stdin, or point AIOS_LUKS_KEYFILE at a file whose first line is the passphrase (it’s never taken from the command line or an environment variable, which would leak via ps//proc).

Housekeeping

aios compact           # reclaim disk: erase tombstoned data + VACUUM  (--yes to skip the prompt)
aios reset             # wipe the whole graph and start fresh          (--yes to skip the prompt)
aios down              # stop the services this launcher started