Chapter 3

Open Pi Agent from the sidebar

The Pi Agent sidebar entry confirms that the add-on is installed. This chapter explains why it appears automatically, why non-administrator accounts cannot see it, and how the same entry works in the Home Assistant Companion App. Pi Agent uses Home Assistant Ingress, so you do not expose a separate port.

Why the sidebar entry matters

After installation, three access questions often arise:

  • “Why can another household member not see it?” Pi Agent is intentionally visible only to Home Assistant administrators because it can use paid API keys and local tools.
  • “Can I open it away from home?” Yes, if your existing HA remote-access method supports the session. Pi Agent sits behind HA, whether you use Nabu Casa, Cloudflare Tunnel, or a VPN.
  • “Do I need a router or firewall rule?” No separate rule is required for Pi Agent. Home Assistant Ingress carries the traffic through HA.

Understanding these boundaries helps you diagnose access problems without exposing another service to the internet.

How Home Assistant Ingress works

Think of Home Assistant as a building’s front desk. An add-on remains inside the building. A visitor authenticates with the front desk, which checks access and forwards the request to the right add-on. Home Assistant Ingress provides that authenticated entry path.

Pi Agent runs pi-web internally. Without Ingress, a self-hosted site might require an address such as http://home-IP:30142. Exposing that address directly would mean:

  1. Adding port forwarding for 30142
  2. Providing and protecting a separate login
  3. Remembering the home IP address remotely
  4. Handling mobile access separately

Ingress avoids those tasks. You sign in to Home Assistant, which embeds Pi Agent and applies the HA authentication and administrator requirement.

Concept: Pi Agent listens internally on 30142. Its config.yaml declares ingress_port: 30142, but you do not connect to it directly. Requests use an HA route such as your-HA-URL/api/hassio_ingress/<token>/..., implemented in homeassistant/components/hassio/ingress.py. HA forwards them to nginx on port 30142 in the add-on container, and nginx forwards them to pi-web on internal port 30141. Your browser remains on the HA origin.
ComparisonIngress, as used by Pi AgentDirectly exposed service
Router changesNone for Pi AgentOften requires port forwarding
Separate passwordNo; uses the HA accountUsually required and separately protected
Companion AppEmbedded in the HA appUsually opened through a separate browser or app
Remote accessUses the existing HA remote-access pathRequires a separate VPN, tunnel, or DDNS setup
Exposed surfaceUses the existing HA entry pointAdds another network-facing service
VisibilityHA administrators only in this configurationDepends on that service’s access controls
Tip: Ingress means inbound entry. In Home Assistant documentation, it refers to the authenticated proxy used to embed an add-on in the HA interface.

Why administrator access is required

For this workflow, the relevant distinction is between administrators and regular users:

RoleTypical accessPi Agent sidebar entry
AdministratorCan manage settings and add-ons and can access Pi Agent SessionsVisible
Regular userCan use the dashboards and entities granted through HAHidden

Pi Agent’s config.yaml sets panel_admin: true below panel_title: Pi Agent. The Supervisor’s IngressPanel exposes an admin flag, and HA registers the panel with frontend.async_register_built_in_panel(..., require_admin=data.admin, ...). The restriction matters because:

  • Pi Agent uses your API keys, which may authorize billable provider usage.
  • Session history may contain device IDs, locations, or other private household details.
  • Skills may run shell commands or modify HA files and settings, depending on their permissions and your approval.
Warning: Do not promote someone to administrator merely to expose Pi Agent without considering the broader access that role grants. The “Give others access” section explains the trade-off.
Pi Agent entry in the Home Assistant sidebar
Figure 3-1 The Pi Agent robot icon appears in the Home Assistant sidebar for administrators.

Open Pi Agent from the sidebar

  1. Sign in to Home Assistant as an administrator

    Open your HA address in a desktop browser, usually http://homeassistant.local:8123 or http://home-IP:8123 on the local network, and enter an administrator account.

  2. Find Pi Agent in the sidebar

    Scroll through the HA sidebar past built-in items such as Overview, Map, Logbook, and History. The Pi Agent entry uses a robot icon (mdi:robot). Its presence confirms that the add-on is running, Ingress is registered, and the account meets the administrator requirement.

    Tip: If it is missing, use the common access problems section below.

  3. Select it and wait 5-10 seconds

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

  4. Locate Open in new tab

    This control opens Pi Agent in a separate browser tab, which is useful when placing HA and Pi Agent side by side. Both views use the same pi-web instance and data.

  5. On a phone or tablet, use the Home Assistant Companion App

    Sign in to the official Companion App with an administrator account, open its navigation menu, and select Pi Agent. The workspace provides the same functions as the desktop view, but some controls collapse on a smaller screen.

Three multi-device scenarios

Pi Agent uses the HA connection. If a device can open HA with an authorized administrator session, it can generally open Pi Agent:

ScenarioHow to connectWhat to expect
Home computer on the LANOpen http://homeassistant.local:8123 or the host’s local IPUsually the lowest interface latency and best layout for long prompts
Home phone or tablet on the LANUse the HA Companion App or the same local address in a browserThe same Ingress path, with a responsive mobile layout
Remote deviceUse your existing HA remote-access method, such as Nabu Casa at xxx.ui.nabu.casa, Cloudflare Tunnel, or a WireGuard/Tailscale VPNIf HA works remotely, Pi Agent should follow; performance depends on both your HA connection and the AI route
Concept: Pi Agent does not need to know whether you are at home. It receives an authenticated request through HA and returns the interface. HA determines the network route.
Tip: If the interface is slow remotely, first compare the HA home page over the same connection. That separates an HA remote-access problem from a Pi Agent-specific problem.

Open in new tab compared with the embedded view

The views contain the same workspace but use different browser routes:

ComparisonEmbedded sidebar viewOpen in new tab
Address/hassio/ingress/woow_ha_pi_agent, the Supervisor frontend route/api/hassio_ingress/<16-to-128-character-token>/..., created by HA through createHassioSession
AuthenticationUses the HA login session cookieThe token acts as a temporary pass, validated through validateHassioSession every 60 seconds
After refreshWorks while the HA session remains validAn expired token may return 404; reopen it from the sidebar
Sharing the URLDo not share it; another user still needs authorized HA accessNever share it; it contains a temporary access token
Best useEveryday accessSide-by-side work on a larger display
Warning: Treat the token in an Open in new tab URL as a temporary credential. Do not include it in screenshots, messages, or public documents. Anyone who obtains a valid token may be able to view your Sessions until it expires.

Give another household member access

The supported way to expose Pi Agent to another HA user is to make that account an administrator: Settings → People → Users → select the user → enable Administrator. After the user signs in again, the Pi Agent entry should appear.

Understand the consequences:
  • An administrator sees more than Pi Agent: all add-ons, system settings, developer tools, backups, and restart controls are also available.
  • If someone only needs occasional help, use Pi Agent yourself and share the screen while present rather than sharing an Ingress token. The Open in new tab control is for your own authorized session, not a sharing link.
  • Do not promote a child account solely for Pi Agent. The role permits system-wide changes.
Tip: Pi Agent currently has no documented per-Session access controls. The README states “Anyone with HA admin login = full pi-web access.” Treat access as all-or-nothing unless a future version explicitly documents finer controls.

Common access problems

  1. Pi Agent is missing from the sidebar

    Check in this order:
    1. Is this account an Administrator? Open Settings → People → Users, select your account, and inspect the Administrator switch.
    2. In Settings → Add-ons → Woow HA Pi Agent → Info, enable Show in sidebar.
    3. Press Ctrl+Shift+R (or Cmd+Shift+R on macOS) to reload the HA frontend.

  2. The main area stays blank

    Wait 10-15 seconds for the first nginx and pi-web load. If it remains blank after 30 seconds, press F12 and inspect the browser Network and Console tabs.
    Multiple _next/… or /api/… responses with 404 can indicate that nginx sub_filter or the injected </head> shim did not apply the Ingress prefix. Check the add-on Log tab and restart the add-on.
    For 403 responses, sometimes with Untrusted API request, first use Add-ons → Pi Agent → Restart. If the documented DOCS procedure requires it, run ha core restart so the Supervisor can register a fresh panel session.

  3. Open in new tab returns 404

    The URL token has probably expired. Return to the Pi Agent sidebar entry, then use Open in new tab again to create a new token. Close the old tab.

  4. The Companion App shows a blank or black view

    Update the official Home Assistant Companion App for iOS or Android. Then open the HA address in Safari or Chrome on the same device. If the browser works, investigate the app; if neither works, check the network and account.

  5. Local access works, but HA itself is unavailable remotely

    This is an HA remote-access problem rather than a Pi Agent problem. Check the status of your Nabu Casa subscription, Cloudflare Tunnel, or VPN. When remote HA access works again, Pi Agent should follow.

FAQ

Do I need an administrator account?
Yes, with the current add-on configuration. panel_admin: true restricts the sidebar panel to administrators. This behavior is defined in config.yaml. Changing and repackaging the add-on to bypass it is unsupported by this guide. Grant administrator access only to a trusted user who needs the broader role.
Can I open Pi Agent on a computer and phone at the same time?
Yes. Both clients use the same pi-web instance and Session files. Refreshing one device should reveal Sessions created on the other. Avoid sending two messages to the same Session at the same time, because the model may receive two consecutive turns.
How is an iPad different from a computer?
The features are the same, and the interface responds to screen width. A tablet may look much like the desktop view; a phone collapses panels such as the Sessions list into a menu. Learn the layout on a larger screen first if possible.
Will pi-web be slow when I connect remotely?
Separate two paths. Interface loading depends on the connection from your remote device to HA. Model response time depends on the route from Pi Agent to the configured AI provider, plus provider load and model behavior. Test the HA interface and model request separately.
Do AI requests pass through Nabu Casa?
Not in the documented architecture. Your browser may reach HA through Nabu Casa, while Pi Agent sends model requests outbound from the HA host to the configured provider. Review your actual network configuration if you need to verify the route.
Can I bookmark Pi Agent?
Yes, but do not save an Open in new tab URL containing /api/hassio_ingress/<long-token>/...; that temporary token is created through createHassioSession and expires. Bookmark the HA home page, such as http://homeassistant.local:8123, and open Pi Agent from the sidebar. You may bookmark http://homeassistant.local:8123/hassio/ingress/woow_ha_pi_agent, the stable Supervisor frontend route using the woow_ha_pi_agent slug from config.yaml. It still requires a valid HA administrator session and an installed add-on.