Runtime image won't download

runtimenetworkinstallation

What you see

The Levee app shows "Preparing container runtime... N%" for a long time, or the percentage stops moving.
Starting a project fails with one of these messages:
- "Container runtime is downloading (N%)."
- "Container runtime is being verified." / "being expanded." / "being loaded."
- "Container runtime provisioning failed."
- "Container runtime image is not installed."
- "Not enough free disk space to provision the container runtime."
The Startup Doctor reports "Container image is missing".

Why it happens

Projects run in a sandbox built on a Windows image that Levee calls the container runtime. It is several gigabytes, so it is not part of the installer. Levee downloads it the first time it starts on a computer. This happens once per computer, not once per project or per user.

Until the download is finished and checked, no project can start. A slow network, a firewall, or a full disk can hold it up.

What you can try

Wait. On first use, the download can take a while. Leave the computer on and the Levee app open, and watch the percentage.
Free some disk space. Levee needs plenty of free space on the system drive (20 GB by default) before it starts the download. Empty the Recycle Bin and remove large files you don't need.
Check your connection. If you are on a hotel, home or guest network, try again on your office network or VPN.
Restart your computer if the percentage has not moved for a long time. Levee starts the download again.
If it still fails, send your IT team the exact message.

For your IT team

On start, the Levee service:

Looks up the runtime image version this Levee release requires (or the version policy pins in container.baseImage) on downloads.vediram.com.
Downloads the image archive.
Verifies its SHA-256 checksum. An archive that fails verification is never loaded.
Expands it and loads it into Levee's private container engine.

A newer image published for the release ring is not downloaded automatically. It only shows as "Container image update available". See Container runtime.

Check the current state

levee runtime status

Look at Phase, Percent and any error. levee doctor prints the same information as Provisioning:, Provisioning error:, Disk sufficient: and Image present: lines.

To start provisioning now and wait for it:

levee runtime ensure --wait --timeout 3600

If the service has just started and its container engine is not up yet, the command keeps asking until the engine accepts, within the timeout. If the timeout expires first, the command prints "Runtime not ready after N s (provisioning continues in the background)" with the last phase and error, or "Runtime not ready after N s: provisioning could not be started." with the reason, and exits with code 5. Provisioning keeps going; run levee runtime status again later.

"Not enough free disk space to provision the container runtime."

Levee refuses to start a download that would leave the system drive with less free space than its safety margin (20 GB by default). Free space on the system drive, then run levee runtime ensure --wait.

Get-PSDrive C | Select-Object Used, Free

You can change the margin with the runtimeProvisioning.diskHeadroomBytes policy setting. Lowering it is not recommended: sandboxes also need space for their own files.

"Could not download the container runtime."

The service could not reach the download host, or every retry failed (3 retries by default). Check, from the affected machine:

Test-NetConnection downloads.vediram.com -Port 443
Invoke-WebRequest https://downloads.vediram.com -Method Head -UseBasicParsing | Select-Object StatusCode

Common causes:

Firewall or web filter. Allow HTTPS to downloads.vediram.com.
Explicit web proxy. The download is made by the Levee service, which runs as Local System, not as the signed-in user. A proxy configured only in the user's browser settings does not apply to it. Allow downloads.vediram.com to bypass the proxy, or host an internal mirror (below).
TLS inspection on your network edge that replaces certificates with one the machine does not trust. Exempt downloads.vediram.com from inspection or deploy your inspection root certificate to the machine store.

Then run levee runtime ensure --wait.

"Preparing the container runtime stalled (no progress). Check free disk space, then retry."

The download or expansion made no progress for too long. This is usually a network interruption or a disk that filled up during expansion. Check free space, then retry:

levee runtime ensure --wait

On slow links, you can raise runtimeProvisioning.downloadTimeoutSeconds (default 1800 seconds) in policy.

"Container runtime provisioning failed."

Read the detailed reason:

levee doctor
levee log tail --component service --since 2h --level Warning

A checksum mismatch means the archive was corrupted or altered in transit, often by a proxy that rewrites large downloads. Exempt downloads.vediram.com from content inspection and retry.

Antivirus makes loading extremely slow

Loading the image writes many small files. Real-time scanning of Levee's engine data folder can make the "being loaded" phase take a very long time. Exclude %ProgramData%\Vediram\Levee\engine\data from real-time scanning. See Planning.

Use an internal mirror

If machines cannot reach downloads.vediram.com, mirror the Levee runtime release files internally and point Levee at the mirror with the runtimeProvisioning.manifestBaseUrl policy setting (Portal: Container & Runtime > Manifest base URL). The mirror must keep the same folder layout as the Vediram download host. Levee still verifies every checksum. See Container settings.

Offline and air-gapped machines

For machines with no route to a download host, pre-stage the runtime image:

Obtain the runtime image archive (.tar) and its checksum file (.tar.sha256) from Vediram Support, for the exact version the machine needs.
Copy both files to %ProgramData%\Vediram\Levee\images\ on the target machine. Keep the same base name, for example levee-base.tar and levee-base.tar.sha256. This folder is open to SYSTEM and Administrators only, so use an elevated session.
Restart the Levee service:
```
Restart-Service LeveeService
```
Confirm with levee doctor that Image present: shows yes.

Levee skips any archive whose checksum file is missing or does not match. See Container runtime.

Before you open a request

Send the output of levee doctor --json and levee runtime status --json with your request. See Collecting logs for support.