Configuration reference

When to use this reference

Under normal circumstances, you do not need to open Pi Agent’s add-on Configuration page. Once you have installed Pi Agent (Chapter 2) and entered your API key (Chapter 6), you can simply launch it from the sidebar. You may go a year without touching Configuration.

You will need to open it in a few specific situations:

• Troubleshooting with logs: Set log_level to debug when you need more detailed diagnostic information.
• Incorrect timestamps: If log timestamps are 8 hours behind your local time, set timezone to Asia/Taipei, or use the appropriate IANA identifier for your location.
• A broken video pipeline: Reinstall video-tools if the Chromium or virtual environment is corrupted. Chapter 18 explains why this may be necessary.
• The environment-variable escape hatch: Use env_vars if your network requires a corporate proxy or you need to change the Chromium download mirror.

Each of the four options corresponds to one of these situations. Every section follows the same format: purpose / default / valid values / when to change it / pitfalls / example.

The key point: API keys are not configured here

This is the easiest detail to miss after upgrading to v0.13.0. The add-on Configuration page has no API key fields. Keys for every provider—including OpenRouter, OpenAI, Anthropic, DeepSeek, Groq, MiniMax, and GLM—are managed in pi-web’s built-in Models panel. Chapter 6 explains the process, and Chapter 21 documents the version change.

The four options in this appendix are add-on container-level settings. They control how the add-on runs, how detailed its logs are, which time zone it uses, and whether to reinstall its video tools. They are entirely separate from choosing an AI provider or API key.

Option 1: log_level—Log detail

When to change it

• Everyday use: Keep info. It includes the information you normally need without producing excessive noise.
• Troubleshooting: Select debug. It records every HTTP request, Skill scan, and provider call. Remember to change it back when you finish troubleshooting.
• Warnings only: Select warn to record warnings and errors. This can suit routine monitoring once the system is stable.
• Errors only: Select error to record nothing but errors. This is not recommended for long-term use, because warnings often provide advance notice of a problem.

Example

log_level: debug

Use this while investigating why a video pipeline failed. It exposes each Playwright startup step and every ffmpeg argument. When you have found the problem, change it back:

log_level: info

Option 2: timezone—Time zone

Why you should set your local time zone

If you leave this setting empty, the Logs page uses UTC. In Taiwan, for example, those timestamps are 8 hours behind local time. An action performed at 8 p.m. therefore appears in the logs at noon, which can make the corresponding entry difficult to find. Setting Asia/Taipei aligns the timestamps with local time; use the correct IANA identifier for your own location.

The setting also affects dates in Session file names. In Taiwan, a Session opened around 11 p.m. can otherwise receive a file name dated earlier that day in UTC, making records harder to reconcile.

Common IANA identifiers

Example

timezone: Asia/Taipei

Option 3: reset_video_tools—Reinstall video tools

When to enable it

• The video pipeline repeatedly fails, but the logs do not reveal the root cause. Chapter 18 explains what video-tools does.
• The installed Chromium version is too old to capture screenshots of certain websites.
• Python packages in the virtual environment no longer match the main add-on application, which can occasionally happen after an upgrade.
• As an annual “spring cleaning”: even if nothing is wrong, you can run it during off-peak hours to refresh Chromium.

Example (one-time use)

reset_video_tools: true

Save → wait for Supervisor to restart the add-on automatically → watch the Logs page for video-tools-init to begin downloading → when it finishes, reload the Configuration page and confirm that the value has returned to false. No further action is needed.

Option 4: env_vars—Environment-variable escape hatch

Common uses

Example

Route traffic through a corporate proxy:

env_vars:
  - name: HTTP_PROXY
    value: http://192.168.1.1:8080
  - name: HTTPS_PROXY
    value: http://192.168.1.1:8080
  - name: NO_PROXY
    value: 127.0.0.1,localhost,homeassistant.local

Leave the list empty when it is not needed:

env_vars: []

Complete configuration example

A typical configuration for a household in Taiwan looks like this. If you are elsewhere, replace Asia/Taipei with the IANA identifier for your location:

log_level: info
timezone: Asia/Taipei
reset_video_tools: false
env_vars: []

If you are investigating a bug and also need to use a corporate proxy:

log_level: debug
timezone: Asia/Taipei
reset_video_tools: false
env_vars:
  - name: HTTP_PROXY
    value: http://192.168.1.1:8080
  - name: HTTPS_PROXY
    value: http://192.168.1.1:8080

Options removed in v0.13.0 (historical reference)

If you upgraded from an older release, you may notice that many fields have disappeared from the Configuration page. Nothing is broken—they have moved. See Chapter 21 for detailed upgrade notes, or use this table as a quick reference:

Common pitfalls

1. Nothing happens after I change a setting

   After editing the Configuration page, select Save at the bottom. In some Home Assistant versions, a floating element can obscure the button; scroll down slightly to reveal it. The add-on restarts and applies your changes only after you save them.

2. Options return to their defaults after the add-on restarts

   This usually indicates invalid YAML—for example, incorrect quoting around timezone or incorrect indentation under env_vars. Open the Logs page and scroll up to find a message containing parse error or invalid config. It should identify the invalid field. Correct the field and save again.

3. pi-web does not detect an entry in env_vars

   There are three likely causes: (1) the name contains an invalid character, such as a hyphen, begins with a number, or contains Chinese characters; (2) pi-web does not recognize that environment variable—not every OPENAI_* or ANTHROPIC_* variable is supported, and pi-web reads only specific proxy and Playwright variables plus a small number of SDK base URLs; or (3) the entry is an API key, which never takes effect here. Enter API keys in the Models panel instead.

4. reset_video_tools is enabled, but video-tools is not downloaded again

   The normal sequence is select true → save → Supervisor restarts the add-on automatically → video-tools-init reads the flag → the download begins. If nothing happens after you save, confirm that: (1) you actually selected Save on the Configuration page—scroll down if a floating element obscures it; (2) the Logs page contains entries from video-tools-init—if you see only “exit <100ms,” the flag was not read; and (3) if it still does not trigger, select Restart manually on the add-on page. After a successful download, reload the Configuration page and confirm that the option has returned to false.

5. timezone is set to Taipei, but timestamps still use UTC

   Use the complete IANA identifier: Asia/Taipei, not Taipei, CST, or +08:00. An invalid value silently falls back to UTC, so it can appear to have been accepted. Enter the correct value, save it, wait for the add-on to restart, and then check the timestamps on the Logs page.

6. Debug logs are consuming too much disk space

   Change log_level back to info or warn. Home Assistant OS normally rotates log files automatically, but on a Supervised or Container installation you may need to remove old files from /var/log yourself. Do not leave debug enabled indefinitely; use it only while troubleshooting.

Frequently asked questions