Skip to Content
DocumentationGetting startedHow the Companion stick works

How the Companion stick works

This page explains how the parts of the Companion stick fit together, from the PC’s firmware up to the models. Each status uses one of the four labels described on the Companion stick page.

Layers

From the bottom of the stack up:

  1. Hardware. An x86_64 PC with UEFI firmware. Apple silicon and arm64 computers cannot boot the stick.
  2. Secure Boot chain. A Microsoft-signed shim, a Canonical-signed GRUB 2.14, and a Canonical-signed kernel. The boot chain section below shows the order.
  3. Boot menu and A/B slots. GRUB boots the active slot. The slots section below explains the two slots.
  4. Companion OS. An Ubuntu 26.04.1 remaster that comes with Docker, Ollama, and Companion Hub.
  5. Docker and Ollama. The container runtime and the local model runtime that come with Companion OS.
  6. Companion Hub. Planned for the stick install.
  7. Model packs. The 128 GB plan puts 21 models on the CI-CACHE partition, in 74.8 GB of its 78.4 GB.

Boot chain

The stick starts the PC through three signed links, in this order. The initial RAM disk is not covered by the signature chain.

Status: Not yet proven for Companion OS. Stock Ubuntu 26.04.1 Desktop boots from a slot with Secure Boot on. The evidence for Secure Boot with Companion OS comes from QEMU and OVMF virtual machines only. The pinned build passed the QEMU harness on a test image: 23 checks and three boots. That run does not show Companion OS under Secure Boot, and the evidence for Companion OS still comes from QEMU and OVMF virtual machines only.

Slots A and B

The stick has two Companion OS slots:

  • Slot A is the CI-BOOT-A partition, which holds the Companion OS image.
  • Slot B is the CI-BOOT-B partition, which is the update slot.

The CI-EFI partition holds the bootloader and the A/B pointer. GRUB boots the active slot. If you want to boot slot B, run ci-stick slot set B.

Switching slots is Built. Booting Companion OS from a slot is Not yet proven.

What is on the stick

The stick needs 57 GiB or more. The 128 GB plan uses six partitions.

PartitionSizeFilesystemWhat it holds
CI-EFI1 GiBvfatThe bootloader and the A/B pointer
CI-SHARED7 GiBexFATLaunchers, installers, and docs
CI-BOOT-A11 GiBrawThe Companion OS image (slot A)
CI-BOOT-B11 GiBrawThe update slot (slot B)
CI-CACHE73 GiB (78.4 GB)exFATModels (the Ollama store) and OCI container images
CI-PERSIST12.4 GiBext4, writableLive persistence

Windows and macOS see CI-SHARED, which holds the launchers, installers, and docs. The plan puts 21 models in 74.8 GB of the 78.4 GB on CI-CACHE.

The chart shows each partition as a share of the combined size of the six partitions. Sizes are in GiB.

Install steps

The install has seven steps. Companion writes each stick before it ships, so steps 1 to 4 apply only to a stick you supply and write yourself. Steps 5 to 7 apply to every stick.

StepWhat you doStatus
1. Get the signed bundleNo release has been signed with the pinned key yet. Get the signed bundle once a release exists.Planned
2. Verify the bundleThe signature check runs before any hashing. Then the tool checks expiry and the rollback floor, then the size and SHA-256. If a check fails, the tool stops.Built
3. Print the planRun ci-stick flash --dry-run. It prints the write plan.Built
4. Write to the stickOn Linux, run ci-stick flash --device --confirm NODE, where NODE is the device node of your stick. The tool reads the stick back after it writes. No release has been signed with the pinned key yet, so a physical stick cannot yet be written from a release bundle.Not yet proven
5. Start the PCStart a UEFI PC from the stick. Stock Ubuntu 26.04.1 Desktop boots with Secure Boot on. Companion OS is not yet proven.Not yet proven
6. Switch slotsRun ci-stick slot set B to boot from slot B.Built
7. First start and pairingStart Companion OS for the first time, then pair the device with your CI Account. See Device pairing.Not yet proven

Writing the stick alone leaves models, Companion Hub, and Companion Memory out.

Last updated on