Installing Without Internet Access

Many Koios machines sit on a network with no route to the internet. That is a supported and common way to run it — but the ordinary install assumes the machine can download Ubuntu updates, Docker, and the Koios image, and none of that works here.

There are two ways around it. They are very different amounts of work.

	What you do	When to use it
Prepare a virtual disk	Build the whole machine on a computer that has internet, then carry its virtual hard disk to the site	Preferred. You are using Hyper-V, or any hypervisor, at the destination
Carry the files across	Install Ubuntu at the site, then transfer Docker and Koios onto it by hand	A physical machine, or a hypervisor you cannot export a disk from

Prefer the first where you can. It moves every step that needs the internet onto a machine that has it: at the site you create a virtual machine, point it at the disk and switch it on, with no packages to transfer and no dependency problems to solve in a room with no way to look anything up.

Option 1: Prepare a Virtual Disk

Build a complete, working Koios machine somewhere with internet. Shut it down, take its virtual hard disk, and attach that disk to a new virtual machine at the site.

Step 1: Build the machine online

On a computer with internet access and Hyper-V, follow the normal path in full:

Creating the Virtual Machine — Generation 2, Secure Boot off, sized for the site it is going to
Installing Ubuntu
Installing Docker Engine
Getting the Koios Image
Running Koios as a Service

Two deliberate differences from the normal path:

Do not activate the license on the build machine

A Koios license is tied to the hardware it is activated on, and the destination virtual machine counts as different hardware. Activating here wastes the activation. Do Licensing Koios at the site, after the machine is running there.

Leave the address on automatic during the build. The site's addresses almost certainly differ from your build network, and you will set the real one after the move. You will not be able to reach the machine by its build address at the site anyway.

Before going further, confirm Koios actually runs here. This is the whole point of building it online — a problem found now is one you are not diagnosing at the site:

sudo systemctl status docker.koios.service

Browse to the build machine's address and check the login page loads.

Step 2: Shut it down properly

sudo shutdown -h now

Shut down, do not save state

Use the command above, or Hyper-V's Shut Down. Do not use Save or Pause, and do not copy the disk while the machine is running — the databases are mid-write and the copy can be inconsistent in ways that only surface later.

Wait until Hyper-V shows the machine as Off before touching the disk file.

Step 3: Copy the virtual disk

The disk is a .vhdx file, in the location you chose when you created the machine. If you did not change it, Hyper-V Manager shows the path under the machine's settings, on the hard drive entry.

Expect it to be large — Ubuntu, Docker and the Koios image together run to several gigabytes even on a dynamically expanding disk. It compresses well if your transfer medium is tight:

Compress-Archive -Path "C:\path\to\koios.vhdx" -DestinationPath "C:\path\to\koios-vhdx.zip"

Copy it to an external drive, and expand it again at the site if you compressed it.

Step 4: Create the machine at the site

On the Hyper-V host at the site, create a new virtual machine exactly as in Creating the Virtual Machine, with one change at the end.

Page	What to enter
Generation	Generation 2 — must match the machine you built
Memory	The same as the build machine, dynamic memory unticked
Networking	Your External virtual switch
Virtual hard disk	Use an existing virtual hard disk, and browse to the `.vhdx` you copied

Then, before starting it, open the machine's Settings → Security and turn off Secure Boot, or set the template to the Microsoft UEFI Certificate Authority option — the same change you made on the build machine. Set the processor count to match it while you are there.

Generation and Secure Boot must match the build machine

The virtual disk carries the bootloader that was installed on it. A Generation 1 machine, or Generation 2 with the default Windows Secure Boot template, will not boot this disk — it powers on and drops to a boot menu, exactly as a mismatched installer ISO does.

Start the machine. It should boot straight to the Ubuntu login prompt, with Koios already installed.

Step 5: Fix the network

This is the step people miss, and the machine looks broken until it is done.

The new virtual machine has a different virtual network adapter from the one you built on, so Linux may give it a different name — and any address configuration naming the old adapter then applies to an adapter that no longer exists.

At the console, check what the adapter is called now:

ip -br link

Then set the site's address using that name, following Changing the Address.

Use your own values

Enter your settings and the commands throughout the installation pages will show them instead of placeholders. They stay in this browser — nothing is sent anywhere, and nothing is saved to Koios.

Server address

Prefix

Gateway

DNS servers

Adapter name

Username

Once applied, confirm it took:

ip -br addr && ip route

You should now be able to reach the machine over SSH from elsewhere on the site network, and Koios in a browser at https://<your-server-ip>.

Step 6: License it

Now activate, on the machine that will keep running: Licensing Koios.

The activation file is generated on the Koios machine and the signed license comes back from the Ai-OPs portal, so you need a way to carry two small files between this machine and one with internet access. A USB stick is fine — they are a few kilobytes.

Deploying the same disk to several sites? A copied disk carries the original machine's host identity, so every clone shares its SSH host keys and machine identifier. For one site that does not matter. For several, regenerate them on each copy after first boot, or build each site its own disk.

Option 2: Carry the Files Across

Use this when there is no hypervisor to export a disk from — a physical machine, most commonly.

Ubuntu installs from its ISO without internet; the installer simply skips the update step. What it cannot do is install Docker or Koios, so you carry both in.

What to gather, before you go

On a computer with internet access:

What	Where from
Ubuntu Server ISO	The Ubuntu website, written to a USB stick
Docker packages for your Ubuntu release and architecture	Ask your Ai-OPs representative for the offline package
The Koios image archive	The customer portal — take the `amd64` or `arm64` build to match the machine

The Docker packages must match both the Ubuntu release and the processor architecture of the target machine. A set built for a different release fails on dependencies, with an error naming a library rather than the real cause — so confirm what you are targeting before you ask for them.

Step 1: Install Ubuntu

Follow Installing Ubuntu as written, including the static address and Install OpenSSH server.

The install works without internet. Two screens behave differently: the mirror test fails, which is expected and does not stop you continuing, and the update phase at the end is skipped.

Step 2: Get the files onto the machine

With the machine on the site network and SSH installed, copy from your laptop — this is far less painful than a USB stick, and it is why the SSH tick matters:

scp -r docker-packages koios-image.tar.gz <your-username>@<your-server-ip>:~/

If there is no route at all between your laptop and the machine, use a USB stick. Ubuntu Server does not mount it automatically:

lsblk
sudo mkdir -p /mnt/usb
sudo mount /dev/sdb1 /mnt/usb

Replace /dev/sdb1 with the partition lsblk showed for the stick, then copy the files out of /mnt/usb.

Step 3: Install Docker from the packages

cd ~/docker-packages
sudo dpkg -i ./*.deb

dpkg does not resolve dependencies, so if it reports missing ones, the package set is incomplete or built for a different Ubuntu release. On a machine with no internet there is no way to fetch what is missing — go back and get a complete set for the right release.

Then confirm it works and enable it at boot:

sudo docker run hello-world
sudo systemctl enable --now docker

hello-world downloads its test image, so without internet it fails at the download step and tells you nothing about Docker itself. sudo docker info is the offline equivalent: it should print the server version without error.

Step 4: Load the Koios image

docker load -i koios-image.tar.gz

Read what it prints — if it reports an image ID rather than a name, the image needs tagging. Getting the Koios Image covers that.

Step 5: Continue as normal

From here nothing is different: Running Koios as a Service, then Licensing Koios.

The service file refers to the image by name, so as long as the load step produced aiopinc/koios:latest, it starts without modification.

Updating an Offline Machine

Both options apply again at upgrade time, and the first one is much less work the second time around: build the new version online, and swap the disk.

For the file-transfer route, only the Koios image changes — Docker is already installed. Download the new archive from the portal, carry it across, docker load it, and restart the service. Updating Koios covers the rest.

Give the outgoing image a name of its own before you repoint latest, so you can roll back — see Getting the Koios Image.

What's Next

Licensing Koios: activate the license on the machine that will keep running
If the Install Goes Wrong: symptoms, causes and fixes

Licensing Koios If the Install Goes Wrong