Why the first download is 720 MB—and later starts take seconds

Two descriptions of the same process

Readers often confuse two points from earlier chapters:

• Chapter 2 says that first startup takes 3–8 minutes—you have just installed the add-on and selected Start, but the UI appears unresponsive while warnings fill the log. It is natural to wonder whether the installation failed.
• Chapter 17 says that the video pipeline needs 720 MB of tools—recording the screen, generating narration, editing video, and burning in subtitles require a substantial toolchain.

They are the same process. The first 3–8 minutes are spent downloading those tools. This chapter connects three details:

1. What gets installed

   Chromium, a Python virtual environment, ffmpeg, fonts, and rclone—organized into three main groups.

2. Where the files go

   The downloaded files live in three locations under /data/pi-agent/. You can inspect them with the File Editor add-on.

3. When installation runs again

   Under normal circumstances: never. It runs again only after you use reset_video_tools, reinstall without retaining data, or restore a snapshot that omitted the rebuildable files.

By the end, you will know when to let installation finish and when to start it again. That saves you from worrying during normal setup or opening a shell simply to delete files by hand.

video-tools is a name for three groups of tools

Inside Pi Agent, video-tools is the collective name for the components required by the video pipeline. It is not a single tool. The 720 MB figure from Chapter 2 refers to the first two groups:

Strictly speaking, the files first downloaded to /data/pi-agent/ are the first two groups: Chromium and the Python virtual environment. Together they total about 600–700 MB. The number varies from 600–720 MB with Playwright and pip dependency versions, which is why this guide uses the approximate figure of 720 MB. The third group is part of the add-on image and arrives with the roughly 300 MB image download.

What happens during the first 3–8 minutes

After you select Start on the add-on page, two processes run in parallel:

1. First process: pi-web starts immediately (a few seconds)

   The sidebar entry described in Chapter 3 becomes available, the UI opens, and you can start chatting within seconds. pi-web is a Node.js application. It needs neither Chromium nor Python for chat, so it is independent of the video pipeline.

2. Second process: video-tools-init downloads in the background (3–8 minutes)

   The startup script pi-web-start.sh checks whether the sentinel file /data/pi-agent/.video-tools-installed exists, then launches the video-tools-init.sh process when installation is required. The script performs four tasks in order:

   • Create the Python virtual environment with python3 -m venv /data/pi-agent/venv, which takes about 10 seconds.
   • Use pip to install playwright, edge-tts, pyyaml, and mutagen, which takes about 30 seconds–2 minutes depending on the network.
   • Ask Playwright to download Chromium to /data/pi-agent/playwright-cache/, which takes about 2–6 minutes and accounts for most of the download.
   • When every required step succeeds, use touch to create an empty file named .video-tools-installed. This records that installation completed.

3. Every later start: skip installation

   When you restart the add-on, Home Assistant, or the host, video-tools-init checks the sentinel and venv/bin/python3. If both are present, it exits with status 0 without reinstalling anything. The log contains only video-tools-init: already installed (sentinel present) — skipping, and the check finishes almost immediately. That is why first startup takes minutes while later starts take seconds.

Where the downloaded files are stored

Everything downloaded during initialization is stored under /data/pi-agent/ on the Home Assistant host. Use the File Editor add-on or SSH to inspect these three locations:

The key term is sentinel. Docker and Linux services often use an empty file to record that a one-time task has completed, rather than repeatedly examining every installed component. If you run cat .video-tools-installed, the output is empty because the file was created with touch.

Important: Home Assistant snapshots exclude these 720 MB

This is the chapter's most important backup detail. Pi Agent's config.yaml contains a backup_exclude list of glob patterns omitted from Home Assistant snapshots. The seven entries include these items related to the video-tools download:

• **/venv/** ← the Python virtual environment included in the 720 MB download
• **/playwright-cache/** ← the Chromium portion of the 720 MB download
• **/projects/**/clips/**, **/projects/**/segments/** ← large, regenerable intermediate video files
• **/home/**/node_modules/**, **/home/**/.cache/** ← npm caches in AI working directories
• **/sessions/*.jsonl.tmp ← temporary, partially written conversation files

Note: rclone.conf, which contains the Google Drive authorization token, is not excluded. It is included in snapshots deliberately. Losing that authorization during a restore could make later push_drive.sh operations fail without an obvious explanation, so the file is worth its roughly 300 bytes of backup space.

There are two reasons for these exclusions:

1. Reason 1: Including them would make every snapshot 1 GB or larger

   A Home Assistant snapshot normally compresses the add-on's data directory. Including Chromium and the virtual environment would add roughly 700 MB to each snapshot. Keeping 12 monthly snapshots on Google Drive or a USB drive could consume about 12 GB for Pi Agent alone, even though those files can be regenerated.

2. Reason 2: s6-overlay installs them again after a restore

   Suppose the Home Assistant host fails and you restore its snapshot on new hardware. The Pi Agent snapshot contains neither venv nor playwright-cache. Although the sentinel itself is restored, video-tools-init skips installation only if the sentinel exists and venv/bin/python3 is executable. Because the virtual environment is missing, the check fails and the 3–8 minute installation runs again. The result is equivalent to the old environment. The snapshot saves about 700 MB, and the restore takes about 5 minutes longer—a worthwhile tradeoff.

What is included in a snapshot? The data you created or configured:

In short: your valuable data is retained; large files that the machine can download again are excluded. Chapter 20 covers the complete backup and restore process.

How to use the reset_video_tools switch

Pi Agent's Add-on Configuration tab includes a special switch named reset_video_tools. It has one purpose: delete the sentinel, virtual environment, and Playwright cache so that initialization can download a clean copy.

Follow these steps:

1. Open the add-on's Configuration tab

   Open Home Assistant → Settings → Add-ons → Pi Agent → Configuration. This is the same page that contains log_level and timezone.

2. Change reset_video_tools from false to true

   It is a Boolean switch. Turn it on (true). No files are removed until the add-on starts with this setting.

3. Select SAVE

   Save the setting. If Home Assistant says that the add-on must restart for the change to take effect, that is expected.

4. Return to the Info tab and select RESTART

   On restart, s6-overlay's pi-web/run reads reset_video_tools: true, runs rm -rf /data/pi-agent/.video-tools-installed /data/pi-agent/venv /data/pi-agent/playwright-cache, and logs reset_video_tools=true — clearing venv + playwright-cache + sentinel. The independent video-tools-init oneshot also starts during boot. Because the reset and initializer run in parallel, check the Logs tab: if initialization skipped before the reset removed the sentinel, restart the add-on once more to begin the 3–8 minute download.

5. Do not turn it off manually unless automatic reset fails

   This behavior was added in v0.13.0 and corrects advice in older tutorials, including early versions of this site. After deleting the files, the startup script calls the Supervisor API (POST /addons/self/options with {"options": {"reset_video_tools": false}}) to set the option back to false. The log entry reset_video_tools auto-reverted to false confirms success. If the Supervisor API call fails—for example, because SUPERVISOR_TOKEN is unavailable or curl reaches its 5-second timeout—the log warns Could not auto-revert reset_video_tools — turn it OFF manually to avoid re-clearing next boot. Only then should you return to Configuration and turn the switch off yourself.

When to use reset_video_tools

This switch is a maintenance escape hatch, not a routine operation. Use this table to decide when it is appropriate:

The rule is simple: reset when the tools are broken, not merely to make them feel clean.

Can you save 720 MB if you do not use the video pipeline?

The honest answer is not through a supported HA add-on setting. This follows from Pi Agent's design:

1. video-tools-init is an s6-overlay oneshot with no off switch

   The HA add-on registers video-tools-init as an s6-overlay oneshot under rootfs/etc/s6-overlay/s6-rc.d/video-tools-init/. It starts in parallel with pi-web and nginx so that chat is available while video tools install. The Configuration tab has no option that disables this oneshot. The script also has no conditional check such as if VIDEO_PIPELINE_ENABLED; that variable does not turn off initialization in the HA add-on.

2. Avoiding installation requires an unsupported customization

   You could fork Woow_ha_pi_agent_add_on, remove rootfs/etc/s6-overlay/s6-rc.d/user/contents.d/video-tools-init, build your own image, and publish it through your own add-on repository. Otherwise, the supported add-on keeps the files even if you never invoke video features. Maintaining a custom fork is considerably more work than leaving 720 MB on disk.

3. The image still contains about 300 MB of ffmpeg, fonts, and rclone

   Those packages are built into the Docker image with apt install. The add-on offers no way to omit them. Removing them also requires a custom Dockerfile and image.

4. Practical advice: let installation run once

   On a 32 GB drive—the official Home Assistant minimum—720 MB is roughly 2% of capacity, and the download normally occurs only once. Keeping the tools is simpler than maintaining a reduced custom image. If 720 MB is decisive, the underlying storage is probably too small for comfortable Home Assistant operation.

How to monitor progress and distinguish slow from stuck

You do not need to wait blindly during the 720 MB download. Open the add-on's Logs tab and find lines beginning with video-tools-init:. bashio prints these entries alongside the pi-web logs. A normal sequence looks like this:

[INFO] Starting pi-web on 0.0.0.0:30141 (data: /data/pi-agent, home: /data/pi-agent/home)
[INFO] video-tools-init: first-run install starting (~720MB, may take several minutes)
[INFO] video-tools-init: creating venv at /data/pi-agent/venv
[INFO] video-tools-init: installing python packages into venv
[INFO] video-tools-init: downloading Chromium into /data/pi-agent/playwright-cache (~600MB)
[INFO] video-tools-init: install complete — sentinel written to /data/pi-agent/.video-tools-installed

Here is what each entry means:

If a stage produces no new output for more than 10 minutes and shows no error, the network or download service is probably slow. Check the following:

• Open Settings → System → Network in Home Assistant—confirm that the host has internet access. If it does not, repair the connection rather than waiting.
• Open Settings → Add-ons → Pi Agent → Info and inspect CPU and memory use—continued CPU activity or increasing memory use suggests that installation is still working. Wait.
• If the log contains “WARNING: chromium download failed”—that installation attempt failed. It does not create the sentinel, so video-tools-init tries again at the next start. You do not need to reset manually unless incomplete files cause later problems.

When the 720 MB does—and does not—download again

This table covers common Pi Agent maintenance actions and whether they trigger another download:

Routine upgrades and restarts do not trigger another download. It normally happens only after removing data, restoring a snapshot that excludes rebuildable tools, or deliberately resetting video tools. Most people therefore see the 3–8 minute process only once.

Troubleshooting

1. The log remains at downloading Chromium for more than 30 minutes

   This is usually a network problem. Playwright retrieves Chromium from its browser download service, which can be slow or blocked on some campus networks, corporate networks, proxies, or ISPs. Check CPU and network activity on the add-on's Info tab. Continued activity suggests a slow download; no activity may indicate a broken connection. Try again at a quieter time, temporarily bypass a VPN or proxy if appropriate, or use reset_video_tools for a clean retry after fixing connectivity.

2. The log shows WARNING: pip install failed and then continues

   The pip step failed, but video-tools-init.sh handles the failure with exit 0 so that it does not block pi-web. Chat therefore works while video Skills fail, often with a message that edge-tts is missing. Review the complete Skill output and confirm that the host can reach the package source. Then run reset_video_tools for a clean retry.

3. Every download step finishes, but /data/pi-agent/.video-tools-installed does not exist

   If pip and Playwright succeeded but the sentinel could not be created with touch, the data directory may have incorrect permissions. Run ls -la /data/pi-agent/ in an authorized add-on shell and inspect the owner. Search the log for “Permission denied.” Reinstalling without retaining data lets Home Assistant recreate the volume, but it also deletes Sessions, Skills, keys, and other persistent data. Back up anything important before considering that last-resort option.

4. A video-pipeline Skill fails silently and produces no video

   This can indicate an incomplete virtual environment: modules appear to exist, but a damaged dependency stops execution. Inspect the full Skill output in the Logs tab and look for a Python traceback. If the cause remains unclear, use reset_video_tools to rebuild the virtual environment.

5. Pi Agent cannot download because disk space is low

   Chromium and the virtual environment need about 700 MB, plus temporary download space. Keep at least 2 GB free; Chapter 2 recommends 3 GB of free space on the Home Assistant host. pip reports No space left on device when capacity runs out. Remove old snapshots under /backup/, old intermediate files under /data/pi-agent/clips/ and segments/ (see Chapter 17), or unneeded conversations under /data/pi-agent/sessions/. Then reset and try again.

6. reset_video_tools fails to return to false, so every restart clears the tools

   The add-on normally calls the Supervisor API to return the switch to false, but that call can rarely fail because of a Supervisor issue or a missing SUPERVISOR_TOKEN. Open Configuration and check whether reset_video_tools remains true, then look for Could not auto-revert reset_video_tools in the Logs tab. If both confirm the problem, turn the switch off manually and save. If it recurs, check whether the add-on is older than 0.13.0; earlier versions do not implement automatic reset.

7. You want to clear only the sentinel instead of changing Configuration

   DOCS.md describes a narrower troubleshooting method. Open an authorized shell attached to the Pi Agent add-on. The source shows docker exec -it <discovered-container-name> bash as an example, but actual container names vary by installation; discover and verify the name before using a host-level command. Run rm /data/pi-agent/.video-tools-installed, then select RESTART on the Info tab. Removing only the sentinel causes pip and Playwright checks to run again without first deleting venv or playwright-cache. Use the full reset when those directories may be damaged.

FAQ