Meet your home AI workstation

Why add an AI workspace?

If you are reading this guide, your Home Assistant (HA) is probably already installed. You can control devices and receive notifications. The next step is not another device; it is a workspace that can help you plan and create.

Consider a few tasks that usually require separate tools or specialist knowledge:

• You want an automation that turns on an entry light after 6 p.m. when a family member arrives, the living room is empty, and it is raining. Writing it yourself may require YAML, templates, and triggers.
• You want help comparing air conditioners for a small bedroom where noise matters. You would otherwise need to research sizing, efficiency, and published noise specifications yourself.
• You want to create a short, accessible video about a Zigbee switch for your family. Scripting, narration, captions, and editing all take time.

Woow HA Pi Agent (called Pi Agent in this guide) runs an AI workspace on your HA host. The interface and local workspace data run at home, while requests to cloud models still leave your network through the provider endpoint you configure. HA backups can include Pi Agent data.

What exactly is Pi Agent?

Pi Agent is a software workspace rather than a physical appliance. It provides a place to converse with an AI model, inspect files and tool activity, and work on tasks that would otherwise require several applications.

Technically, Pi Agent is a Home Assistant add-on. In Home Assistant, you install and start it from the add-on interface. It then appears as Pi Agent in the HA sidebar.

The add-on bundles several components:

• pi-web: the web interface you use as the workspace desktop.
• pi coding agent: the AI agent behind pi-web, with tools for reading, writing, and running files when you authorize a task.
• Video workflow (pitch_video): a collection of ffmpeg, Playwright, edge-tts, and rclone tools. The first start downloads about 720 MB of supporting files.

You do not need to memorize the component names. For now, remember that Pi Agent is a workspace hosted by your HA system.

Four things Pi Agent can help you do

These four examples show the main uses of the workspace:

1. Draft HA automations without writing YAML from scratch

You might ask: “After 6 p.m., when a family member’s phone connects to the home Wi-Fi, turn the entry light on in white for 30 seconds.” Pi Agent can inspect the available context, propose the triggers and YAML, and present the change for review. Confirm that the entities and behavior are correct before applying it.

2. Research household decisions

You can describe the room, occupants, noise requirements, and budget for an appliance purchase. Pi Agent can help organize the criteria and research current specifications. Verify prices, availability, and safety-critical advice with authoritative sources before buying.

3. Build a video workflow

For example: “Create a 90-second video outline for this motion sensor, explain three verified features, use an English voice available in my TTS setup, and add English subtitles.” Depending on the installed Skill and tools, Pi Agent can help draft the script, narration, capture plan, edit, subtitles, and output steps. Chapter 17 explains the workflow.

4. Teach it a repeatable process with Skills

A Skill is an operating procedure for the agent. For example, a Skill could require the agent to ask for room size, occupancy, and budget before discussing an air conditioner. You can write Skills or install shared ones from GitHub. Chapter 14 introduces the system.

How Pi Agent differs from the ChatGPT app

Pi Agent and a consumer chat app can both produce text, but they have different operating models:

Check that your system can run it

Pi Agent is a Home Assistant add-on. Of the four common HA installation types, only two include the Supervisor and add-on support:

Minimum hardware guidance:

• Architecture: amd64 or aarch64 (arm64), including x86 mini PCs, Raspberry Pi 4/5, and many arm64 single-board computers.
• Memory: 2 GB can run the basic workspace; 4 GB or more is recommended.
• Storage: leave at least 5 GB available for /data/pi-agent/, including the 720 MB video tools. Video projects may require substantially more space; the source recommends 20 GB.
• Network: the HA host needs outbound internet access for cloud-model requests.

5-minute HA review

This guide assumes HA is installed and accessible. Confirm these five items before continuing. If any are unfamiliar, review the HA Onboarding Guide first.

1. Log in to HA

   Open http://homeassistant.local:8123 or your HA host’s IP address and sign in. You must use an Administrator account to install add-ons. If your account is not an administrator, ask the HA owner to grant the appropriate access or perform the installation.

2. Find Settings

   The gear icon labeled Settings appears near the bottom of the HA sidebar. You will use it to reach add-ons, system information, and people.

3. Confirm that Add-ons is available

   Open Settings and locate Add-ons. If it is present, your installation should be HAOS or Supervised. If it is absent, verify whether you are running Container or Core, which this guide does not cover.

4. Recognize the sidebar

   The vertical navigation contains items such as Home, Map, Energy, and History. After installation, Pi Agent appears alongside these items.

5. Find the System page

   Open Settings → System and locate areas such as General, Updates, Hardware, and Backups. Chapter 20 explains how HA backups include Pi Agent data.

How to use this guide

The guide has 22 chapters organized into 6 parts:

Two suggested paths:

• Fast path: read ch1→ch2→ch5→ch6→ch7 to reach a basic working conversation and automation workflow.
• Complete path: read the chapters in order, including Skills and video workflows.

Where Pi Agent data lives

Pi Agent stores several kinds of data on the HA host:

• Conversation history: under /data/pi-agent/, in data included by the documented HA backup path.
• API keys: since v0.13.0, provider configuration is stored through the pi-web Models panel in /data/pi-agent/models.json, rather than in the add-on Configuration page.
• Skills: installed under /data/pi-agent/skills/.
• Video project files: stored under /data/pi-agent/home/pi-cwd-*/. The documented backup behavior excludes intermediate clips/ and segments/ directories while retaining finished mp4 files.

Common setup pitfalls

1. I have not installed HA

   Start with the HA Onboarding Guide. Return after HA is installed, you can sign in, and you can control at least one device.

2. I cannot find Add-ons

   Open Settings → System → About and check the installation type. HAOS and Supervised support add-ons. Container and Core do not, so their native pi-web setup falls outside this guide.

3. My household is uncomfortable with an AI workspace

   Explain the actual boundaries rather than making blanket assurances. Pi Agent does not add a microphone or camera, but it can use the tools and permissions configured for it. Cloud providers receive the requests sent to their models. Start with low-risk tasks, review proposed changes, and limit access to trusted administrators.

4. I am concerned about data exposure

   Keep keys in the Models panel and a password manager, restrict HA administrator access, back up securely, and review provider retention and privacy settings. Local conversation files under /data/pi-agent/ are not a third-party backup, but anyone with sufficient host access can read them. Do not assume a provider’s region or route without checking its current documentation.

5. Can a Raspberry Pi 4 with 2GB run it?

   It can handle chat and automation work, but Playwright and Chromium make video workflows resource-intensive. Use the first 16 chapters for text-based tasks and move video work to a better-equipped x86 system or Raspberry Pi 5 with 8GB if performance is inadequate.

FAQ