One line in the sidebar, and what it proves

Pi Agent gets no desktop shortcut, no address of its own and no login screen. It gets one entry in the Home Assistant sidebar with a robot icon. That single line is a three-part status report: the add-on is running, its Ingress panel is registered, and your account is an administrator. Fail any one and the entry is simply not there.

Scroll the sidebar past the built-in items your installation shows and look for the robot icon, mdi:robot. The wording beside it comes from the add-on's own config.yaml, which sets panel_title: Pi Agent — the label to scan for unless someone renamed it.

1. Step 1

   Sign in to Home Assistant as an administrator

   Open your usual HA address in a desktop browser — on the local network that is normally http://homeassistant.local:8123 or http://home-IP:8123 — and sign in with an administrator account.

2. Step 2

   Select Pi Agent in the sidebar

   The workspace opens in the main area. The first load may take 5-10 seconds while the request travels through Ingress to nginx and then to pi-web. Later loads should be faster.

3. Step 3

   Note where Open in new tab is

   It opens the same workspace in its own tab — useful for putting Home Assistant and Pi Agent side by side. Both use the same pi-web instance and the same data.

4. Step 4

   On a phone or tablet, use the Companion App

   Sign in to the official Home Assistant Companion App as an administrator, open its navigation menu, select Pi Agent. Same functions, though some controls collapse on a small screen.

Home Assistant is the front desk

Inside the add-on, the program that does the work is pi-web, listening on internal port 30141. In front of it sits nginx, on the add-on's declared ingress port 30142. Without Ingress you would reach that port yourself at something like http://home-IP:30142, which brings four chores: forwarding port 30142 on your router, protecting a separate login, remembering your home IP when you are out, and sorting out mobile access.

Ingress removes all four: you sign in to Home Assistant, and it embeds the workspace after its own authentication and administrator check.

flowchart LR
  A["Your browser
still on the HA address"] --> B["Home Assistant
login session and admin check"]
  B --> C["Ingress proxy"]
  C --> D["nginx in the add-on
port 30142"]
  D --> E["pi-web
internal port 30141"]

Whatever you already use to reach Home Assistant from outside — Nabu Casa, a Cloudflare Tunnel, a VPN — Pi Agent inherits it. Nothing new to set up, nothing new pointed at the internet.

The entry is hidden from everyone else on purpose

The add-on declares panel_admin: true, so Home Assistant registers the panel as administrator-only. A regular user does not see a greyed-out entry — they see no entry.

Three things sit behind that panel, and each is a reason for the restriction:

• Your API keys, which may authorize billable usage at a provider.
• Session history, which may contain device IDs, locations or other private household details.
• Skills, which may run shell commands or change Home Assistant files and settings, depending on their permissions and your approval.

You can give another household member access, and the supported way is the blunt one: Settings → People → Users, select the user, enable Administrator. They sign in again and the entry appears.

Five areas to be able to point at

The workspace behind the icon is pi-web, and it is not a Home Assistant dashboard with a different skin.

On a wide screen it splits into a left column, a center and a thin top bar; on a narrow one some of that collapses into menus. Move your pointer over each in turn — nothing to click yet.

A new conversationThe message box is empty because this conversation has not started. The machine behind it has plainly been used before.web v0.9.0 · pi v0.85.1

• + New at the top of the left column, with the working directory ~/pi-cwd-20260909 just below it. One conversation per separate task; the path is where the agent's file tools land.
• The session list under that — here three earlier conversations, each with a relative time and a message count, such as 36 minutes ago · 8 msgs. A brand-new install has no entries; this one is not.
• EXPLORER below the list, showing what is in that working directory — one file, notes.md. It is the fastest way to see what the agent has actually written.
• Models, Skills and Settings sit as three buttons along the bottom of the left column in this build. That is where those panels open from.
• The message box in the center, reading Message… Type / for commands, @ for files, with Send at its right end. The row beneath it carries the model name, GPT-5.6 Sol, then auto, default and Compact. System and Tools live up in the top bar.

The model name below the box is the one to watch, because it tells you where you are in the setup:

Everything opens as a drawer over the conversation

A panel here is a drawer over the workspace — not a Home Assistant sidebar panel, and not a page you navigate to. Close it and you are back in the same conversation. In the build pictured above, Models, Skills and Settings open from the buttons at the foot of the left column, System and Tools from the top bar.

Two are worth opening now, purely to look. First the tool list — the agent's actual reach.

ToolsWhat the agent can do, spelled out one tool at a time, with the exact inputs each one takes.

• read, bash, edit, write in the left column — these are the verbs, and the honest answer to “what can it actually touch?” Worth knowing, because a tool call card in a conversation is labeled with one of them.
• Select read and the right column fills in: path is required and takes a string, offset and limit are optional numbers. That is the level of detail the model is working from.
• Under the parameters the panel begins a Prompt guidelines section — the wording the model itself reads about using that tool.

The second is the system prompt: the standing instructions the agent carries into every message, including any loaded Skill descriptions.

SystemThe full instructions, readable rather than hidden. Part 5 comes back to this when reasoning blocks start appearing.

Appearance and comfort settings live apart from those.

GeneralAppearance, content width and font size — and the switch that decides whether reasoning blocks arrive open or closed.

• Light / Dark / System is pi-web's own theme, set to System here. Home Assistant's theme is set in your HA profile and does not carry over.
• Expand thinking blocks by default is off in this build, so a model's reasoning arrives collapsed. Leave it off until Part 5 explains what you are reading.
• Chat content width at 820px and Chat font size at 14px are the two that make long answers readable on a wide monitor.
• The tabs across the top — General, Models, Skills, Sub-agents, Plugins — are where the panels in the table above live here.

There are exactly two global shortcuts: Esc stops a running agent, and Ctrl+Alt+N opens a new session in the current working directory. There is no command palette and no Cmd+K. In the message box itself, Enter sends and Shift+Enter starts a new line.

The problems people actually hit

Where to go from here