Install the local-first version

Penduline on your own machine, against your own Home Assistant. It reads. It never switches anything. Your token stays on your machine.

Read this first: the source is not public yet

Penduline's source is not public yet. The GitHub repository is private, so github.com/AQuantumArchitect/penduline shows "404" to anyone without access. There is no PyPI package, no GitHub release, no published Docker image and no Home Assistant add-on. When any of that changes, this page will say so. No date has been decided.

If you do have access to a checkout, the steps below work from it. If you do not, you cannot install Penduline yet; see how to ask about the beta.

1. You need

Python 3.11 or newer, and git.
A Home Assistant you can reach, and permission to make a long-lived token in it.
A checkout of Penduline. Run the commands below from inside it.

2. Install

Umwelt, the engine, is public. It is installed from its pinned tag; no token is needed.

python3 -m venv .venv && . .venv/bin/activate
pip install "umwelt-engine @ git+https://github.com/AQuantumArchitect/umwelt-engine@v0.2.1"
pip install .
penduline --help

3. Your token, kept on your machine

In Home Assistant: click your name at the bottom of the sidebar (Profile), open Security, scroll to Long-lived access tokens, Create token, copy it once. Then:

mkdir -p ~/.penduline
cat > ~/.penduline/.env <<'ENV'
HA_URL=http://homeassistant.local:8123
HA_TOKEN=paste-your-long-lived-token-here
ENV
chmod 600 ~/.penduline/.env

Penduline sends the token only to your own Home Assistant. It is never part of the package.

4. First run

Census counts what is placed, ignored, or unaccounted for. It reads your Home Assistant; it writes nothing to it.

penduline --house mine census
penduline --house mine draft
penduline --house mine overlay
penduline --house mine census

"Not honest" on the first census, and exit code 2, is normal: it lists what is unaccounted for. draft only suggests; overlay asks a few questions and you decide. Repeat until census says "honest": true. Then:

penduline --house mine confess --live
penduline --house mine bridge --stage watch

confess prints what each room would say, one line each, and writes nothing. bridge --stage watch feeds the engine from your Home Assistant and writes nothing back. Before census is honest, bridge will not ingest. If something is wrong, run penduline --house mine doctor; it never prints your token.

To work from an export instead of a live connection, save your entities to ~/.penduline/states.json and add --from-file ~/.penduline/states.json to census, draft, overlay and confess.

5. Uninstall

pip uninstall penduline umwelt-engine
rm -rf ~/.penduline

Then delete the long-lived token in Home Assistant (Profile, Security). At the Watch stage Penduline created nothing in Home Assistant.