Your home's energy, from wherever you are.
This is FTW's installable web client. It talks to the FTW box in your home, which is the authority on your energy system. Its encrypted session runs through FTW Cloud, as on iPhone.
The shared FTW vision guides the client: fast, honest live feedback; simple daily charging; useful expert access; and clear outcomes for both people and authorized agents. The roadmap states acceptance evidence. Goals such as cloud MCP access are distinct from implemented protocol support.
Sourceful maintains the app. PRs are welcome, preferably based on issues. Share a short Markdown proposal or a focused fix with relevant test evidence. See CONTRIBUTING.md.
webapp → Noise to FTW Cloud → tun → Noise to the home box
│
state, safety, control
Three claims hold this together:
The box is the record. It measures, controls, stores the full history and decides what is safe. It works with the cloud switched off. The app holds a cached projection of it, never the original.
The app renders from its own cache first. Press the icon and readings are on screen in the first frame, timestamped honestly, while fresher data is fetched behind them. There is no spinner on a white background.
The box session stays encrypted. FTW Cloud cannot read or forge the
session inside tun. It sees a stable home id, the box's address and traffic
timing. Remote access works with the readable copy off. If an owner enables
that copy, Sourceful can read the data it contains; this web client still
reads through its own box session. ADR 0008
and the Cloud protocol
describe that boundary. The relay and escrow remain blind.
Pairing needs a current box and QR v3. Existing web installations must pair
again. The passkey origin stays app.ftw.energy. There is no relay fallback.
If a household asks, the escrow will also hold one sealed copy of its home, so a
new phone gets back in with a passkey instead of a trip to the box. Sourceful
holds a sealed copy it cannot open, with an opaque id and nothing beside it —
escrow/README.md is the claim, the file of fixed slots it
is stored in, and the tests. It is off until someone turns it on, and losing the
whole database costs a QR scan.
See docs/architecture.md for the architecture and docs/protocol.md for the wire contract. Some design notes record earlier delivery stages; use the current implementation, tests and release evidence to establish what a particular box and app support. The product vision is a target, not an availability list.
Not yet built in this web client: the WebRTC LAN carrier, Cloud push for browsers and reading the optional signed copy. This change carries the box session.
npm install
npm run devFor local integration work, run make dev in
FTW. That starts simulated drivers and seeds
history, so no hardware is needed.
npm run verifyRuns type checks, tests and a production build. Green before every handoff.
| Path | What lives there |
|---|---|
src/lib/protocol |
Wire format, capability negotiation, snapshot and deltas |
src/lib/carrier |
The Cloud tunnel and local cache; relay code remains for server tests |
src/lib/crypto |
Noise IK, the passkey key hierarchy |
src/lib/identity |
Enrollment, principals, grants |
src/lib/store |
IndexedDB — the local projection |
src/lib/ui |
Components |
src/views |
Screens |
contract/ |
The shared registry: scopes, capabilities, error codes, field ids |
relay/ |
The old blind relay, pending service retirement |
escrow/ |
The sealed escrow — one slot per household, and it cannot open any of them |
contract/registry.yaml is the single source for every name shared with the
box. It generates TypeScript here and Go constants in the FTW repo, and CI
fails if the two drift. Do not hand-write those names in either language.
AGPL-3.0-only with the Energyplan combination permission. See LICENSE, LICENSING.md and NOTICE. Earlier Apache-licensed versions retain their earlier grants.