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:
- Hardware. An x86_64 PC with UEFI firmware. Apple silicon and arm64 computers cannot boot the stick.
- 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.
- Boot menu and A/B slots. GRUB boots the active slot. The slots section below explains the two slots.
- Companion OS. An Ubuntu 26.04.1 remaster that comes with Docker, Ollama, and Companion Hub.
- Docker and Ollama. The container runtime and the local model runtime that come with Companion OS.
- Companion Hub. Planned for the stick install.
- 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.
flowchart TD
accTitle: Boot chain of the Companion stick
A["Microsoft-signed shim"] --> B["Canonical-signed GRUB 2.14"]
B --> C["Canonical-signed kernel"]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.
| Partition | Size | Filesystem | What it holds |
|---|---|---|---|
| CI-EFI | 1 GiB | vfat | The bootloader and the A/B pointer |
| CI-SHARED | 7 GiB | exFAT | Launchers, installers, and docs |
| CI-BOOT-A | 11 GiB | raw | The Companion OS image (slot A) |
| CI-BOOT-B | 11 GiB | raw | The update slot (slot B) |
| CI-CACHE | 73 GiB (78.4 GB) | exFAT | Models (the Ollama store) and OCI container images |
| CI-PERSIST | 12.4 GiB | ext4, writable | Live 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.
pie showData
accTitle: Partition sizes in the 128 GB plan
title Partition sizes in GiB
"CI-CACHE" : 73
"CI-PERSIST" : 12.4
"CI-BOOT-A" : 11
"CI-BOOT-B" : 11
"CI-SHARED" : 7
"CI-EFI" : 1Install 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.
sequenceDiagram
accTitle: Install steps for the Companion stick
actor You
participant Rel as Release bundle
participant Tool as ci-stick on Linux
participant Stick as Companion stick
participant PC as x86_64 UEFI PC
You->>Rel: 1. Get the signed bundle
Note over Rel: Planned
You->>Tool: 2. Verify the bundle
Note over Tool: Built. If a check fails, the tool stops
You->>Tool: 3. Print the plan with flash --dry-run
Note over Tool: Built
You->>Tool: 4. Write with flash --device --confirm NODE
Tool->>Stick: Write, then read back
Note over Stick: Not yet proven. No physical write is recorded
You->>PC: 5. Start the PC from the stick
Note over PC: Not yet proven for Companion OS
You->>Tool: 6. Switch slots with ci-stick slot set B
Note over Tool: Built
You->>PC: 7. First start and pairing
Note over PC: Not yet proven| Step | What you do | Status |
|---|---|---|
| 1. Get the signed bundle | No release has been signed with the pinned key yet. Get the signed bundle once a release exists. | Planned |
| 2. Verify the bundle | The 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 plan | Run ci-stick flash --dry-run. It prints the write plan. | Built |
| 4. Write to the stick | On 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 PC | Start 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 slots | Run ci-stick slot set B to boot from slot B. | Built |
| 7. First start and pairing | Start 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.