An add-on, not another app to sign into

Pi Agent installs the way any other Home Assistant add-on installs. When it finishes, a new entry appears in your left sidebar. You click it and you are in a workspace that looks a bit like a chat window — except this one can read files, run commands, and change things on the machine it lives on.

That is also why it is not simply a chat app you could have opened in a browser tab. Three things follow from living inside Home Assistant:

• It reaches your files. The workspace has a file explorer and a terminal, pointed at a folder on your Home Assistant host.
• It uses your Home Assistant login. There is no second account to create. If you are signed into Home Assistant, you are signed into this.
• Your side stays on your side. The files, the terminal and the workspace are on your hardware. Only the text of a request goes out to a model provider, and only when you send one.

flowchart LR
  A["Your browser"] --> B["Home Assistant Ingress"]
  B --> C["nginx inside the add-on"]
  C --> D["pi-web, the workspace you see"]
  D --> E["pi coding agent SDK"]
  E --> F["Files and terminal on your host"]
  E --> G["Model provider on the internet"]

The one part that is genuinely new is the last arrow. Everything else in Home Assistant runs on rules you wrote. This part sends your words to a model somewhere else and brings back an answer. That is the trade, and it is worth knowing before you install.

Two things to check before you start

Most of the requirements take care of themselves. Two do not, and both are quick to check.

Does your Home Assistant support add-ons?

Only some ways of running Home Assistant can install add-ons at all. Go to Settings → System → About and read the installation type.

Are you an administrator?

Installing add-ons needs an administrator account. If your Home Assistant profile is a normal user, the Add-ons section will not appear in Settings at all — which is confusing, because it looks like the menu is broken rather than hidden.

And the rest, briefly

• Processor: amd64 or aarch64 — which covers x86 mini PCs, Raspberry Pi 4 and 5, and most arm64 single-board computers.
• Memory: 2 GB will run the workspace. 4 GB or more is the comfortable figure once you start using the video tools.
• Disk: leave about 3 GB free. That is not a published hard minimum — it is room for the download, logs, cache and your Home Assistant backups.
• Network: the host needs to reach ghcr.io to pull the image.

Adding the repository, then the add-on

Pi Agent is not in the official add-on store. It lives in a repository maintained by WoowTech, which means you tell Home Assistant where to look before you can install it. That is what the first three steps are for.

1. Step 1

   Open Settings, then Add-ons

   Go to Settings → Add-ons. If you do not see Add-ons in the Settings menu, go back and check the two things in the previous section — installation type and administrator rights.

2. Step 2

   Open the store, then the three-dot menu

   Click Add-on store at the bottom right, then the three-dot menu at the top right of that page, then Repositories.

3. Step 3

   Paste this address and select Add

   Paste the repository address below into the box, then select Add, then Close.

   https://github.com/WOOWTECH/Woow_ha_pi_agent_add_on

   The store page will reload with a new section on it.

4. Step 4

   Find Woow HA Pi Agent and open it

   Scroll to the WoowTech HA Pi Agent Add-on Repository section and click the add-on. You land on its Info page, which is the screen shown below.

5. Step 5

   Select Install and wait for the image

   This pulls a container image of roughly 300 MB. On a Raspberry Pi with a normal connection the install steps take about 4-6 minutes end to end; on an x86 mini PC or NUC, about 1-2 minutes. Actual download time varies with your connection.

6. Step 6

   Turn on Start on boot, Watchdog and Add to sidebar

   Three toggles are worth setting now. Start on boot brings it back after a power cut. Watchdog restarts it if it crashes. Add to sidebar is what puts the entry in your left menu — without it the add-on works but you have to come back to this page every time.

   Leave Autoupdate off. Upgrades are worth doing deliberately, which Part 15 covers.

7. Step 7

   Select Start

   The status turns to Started in roughly 5-15 seconds. That is when most people click straight through to the workspace and find it blank — which is the subject of the next section, and is normal.

The Info pageWhere steps 4 to 7 happen. Captured after the install and the first start, which is why the bottom row reads Stop and Restart rather than Install.

• Current version: 0.12.0 sits under the title, with a Changelog link beside it. Note the number down — it is the first thing anyone will ask if you report a problem.
• Ingress is the blue badge, next to the green Rating badge. That badge is why access follows your Home Assistant login instead of a separate password.
• Start on boot, Watchdog and Add to sidebar are on here, and Autoupdate is off. That is exactly the combination step 6 asks for.
• Add-on CPU usage and Add-on RAM usage in the right column both read 0% on an idle add-on. Remember where they are — they are the quickest sanity check when something feels wrong.
• Open web UI is the blue button at the bottom right, beside Uninstall. Stop and Restart are at the bottom left, which is where you will come back to for Part 15.

Started does not yet mean ready

This is the part that catches people out, so it is worth understanding rather than just waiting through.

When the add-on says Started, the workspace itself is already running. But a background service called video-tools-init is still working, and until it finishes, opening the workspace can show you a blank page, a loading spinner, or a connection refused message. None of those mean the install failed.

What it is unloading is roughly 720 MB of video tooling, in four steps:

flowchart TD
  A["Add-on says Started
about 15 seconds"] --> B["1 · Create a Python environment
about 20 seconds"]
  B --> C["2 · Install playwright, edge-tts,
pyyaml, mutagen
about 30-90 seconds"]
  C --> D["3 · Download and extract Chromium
the big one, 2-6 minutes"]
  D --> E["4 · Write the completion marker
/data/pi-agent/.video-tools-installed"]
  E --> F["Workspace fully ready"]
  F -.->|"every later start"| G["Marker found, so this whole
column is skipped in under 100 ms"]

The source puts the whole first start at 3-8 minutes on a Raspberry Pi and 1-2 minutes on x86. Those totals sit awkwardly next to the 2-6 minutes documented for step 3 alone, so treat the x86 figure as a floor rather than a promise, and give it the benefit of the doubt before deciding something is wrong.

You can watch it happen rather than guess at it. On the add-on page, open the Log tab — that is where the add-on writes its output, first start included, and it is the first place to look for any problem later.

The Log tabLog is the fourth tab along the top. This capture is from an add-on that has been running for a while, so what fills the panel is routine web traffic rather than first-start output.

• Search logs filters the lines. Worth knowing about early — the panel is thousands of lines long within a day.
• Live, bottom right, means the view is still following new output as it is written. That is the state you want it in during the first start.
• The lines here are nginx access entries — one per request your browser made through Ingress. Steady traffic like this is a sign of a healthy add-on, not a fault.
• Those lines contain an Ingress session identifier. Trim them before you paste a log into a forum or an issue.

What the workspace looks like

Click the new entry in your sidebar, or Open web UI on the add-on page. Both go to the same place.

The capture below is from a machine that has already been used for a while, so its sidebar has conversations in it and a file in the explorer. A fresh install has the same furniture with nothing in it yet. Learn the layout from this one; the empty version of it is what you will see.

A conversation waiting to be typedTaken on an instance that has been in use, which is why the list on the left is not empty. Your own will be.

• + New, top left, starts a conversation. Everything under it is history and files rather than anything you have to set up.
• ~/pi-cwd-20260909 is the project path — the folder on your Home Assistant host this workspace is pointed at. Yours will carry a different date.
• The conversation list holds three entries here, each with an age and a message count. Two are titled in Chinese: the interface is English, but you write to it in whatever language you like.
• EXPLORER, further down the same column, lists what is in that folder. This one has a notes.md in it from earlier work.
• Models, Skills and Settings sit in a row across the bottom left corner, not the top. Models is where Part 3 sends you.
• The message box in the middle is the whole interface. The row beneath it names the current model — GPT-5.6 Sol on this machine — next to auto, default and Compact.

That model name is the one part of the picture a new install will not have. Nothing sits behind that button until you connect a provider, so anything you type now goes nowhere. That is Part 3. At this point the only thing that needs to be true is that the page loads and has these parts in it.

Four things that actually go wrong

Where to go from here