teslakit 0.1.0

Self-host the Tessie experience: Docker Compose for HA + TeslaMate + Tesla HTTP Proxy + BLE.

teslakit

Self-host the Tessie experience. One Docker Compose file bundling Home Assistant, the Tesla HTTP Proxy, the BLE bridge, TeslaMate, Mosquitto, Postgres, Grafana, and an optional Caddy reverse proxy. Plus a Python wizard that walks you through Tesla developer credentials, generates secure DB passwords, and validates everything before you run docker compose up -d.

Replaces a $13-20/month SaaS subscription with infrastructure you own.

Install

teslakit ships as a CLI on PyPI plus a Docker Compose monorepo on GitHub. The canonical install path is git clone because the wizard configures the compose stack sitting next to it:

git clone https://github.com/Raymondriter/teslakit.git
cd teslakit
uv sync --extra dev
uv run teslakit init

If you only need the wizard CLI itself (e.g. to inspect the component inventory before deciding whether to clone the repo), the wheel works standalone:

pip install teslakit
teslakit --help
teslakit components

teslakit init, teslakit doctor, and teslakit summary look for ./docker-compose.yml and ./.env in the current working directory, so they need to be run from a clone of the repo to do anything useful. See RELEASE.md for why the Compose file isn't shipped inside the wheel.

License: AGPL-3.0-or-later — teslakit bundles TeslaMate v3.0.0+ which switched MIT → AGPLv3 in February 2026; teslakit matches.

Why this exists

The wave-3 spec at ../ideas/v2/wave3/selfhost_tessie_kit.md found that ~93% of Tessie's 29 documented features have an OSS equivalent shipping in May 2026. The gap was integration glue — every component existed, nobody had packaged them. teslakit is that package.

What you get

• Home Assistant — the dashboard, voice pipeline, integration host, MCP server (for hey-nabu)
• Tesla HTTP Proxy — signs Fleet API commands per the post-2024 SDK requirement; powered by teslamotors/vehicle-command v0.4.1
• tesla_ble_mqtt — local BLE bridge so Sentry/charge/climate work without a cloud round-trip
• TeslaMate v3.0.0 — drives, battery health, Grafana dashboards (the new teslamate-org org, AGPLv3)
• Mosquitto — MQTT broker bridging the BLE side to HA
• Postgres + Grafana — TeslaMate's data store + dashboard host
• Caddy — optional public HTTPS reverse proxy with Let's Encrypt
• teslakit init — interactive wizard that generates passwords, prompts for credentials, validates before save
• teslakit doctor — health check that verifies env vars + flags stale component pins
• teslakit components — render the pinned-version inventory as a table

Status — v0.1 alpha

What works today:

• Docker Compose file with 8 services, all version-pinned, profile-gated for the optional Caddy public proxy
• Setup wizard with multi-step state machine (tesla_credentials → db_password → validate) that's idempotent (re-running picks up where you left off) and saves env after every successful step (so a crash mid-flow preserves progress)
• Component inventory at src/teslakit/components.py — versions, licenses, last-checked dates, status flags ("active", "active-but-orphan-risk", "frozen", "abandoned"). The doctor command warns when pins are >90 days stale.
• Secrets management — env file reader/writer that preserves order + comments, masks values for display, generates random passwords, has a sane is-placeholder heuristic
• Tests — 36 unit tests covering env file management, the placeholder heuristic, password generation/uniqueness, every wizard step (happy path + every rejection branch), the run_wizard driver (full happy path + first-failure-stops), summary masking, and the component inventory invariants

What's not in v0.1 (planned for v0.2+):

• HA Supervisor add-on shape (current setup is HA Container)
• Bootable Pi / x86 image (for users who want fully turnkey)
• ESPHome firmware flasher integrated into the wizard (currently you flash separately)
• The wizard's auth subcommand to mint a long-lived HA token + write it back into .env
• Lovelace dashboard package (Tesla-themed cards)
• Backup/restore commands

Quick start

git clone https://github.com/Raymondriter/teslakit.git
cd teslakit
uv sync --extra dev

# Run the wizard. It copies .env.example -> .env then prompts for missing values.
uv run teslakit init

# Sanity check
uv run teslakit summary    # masked view of your .env
uv run teslakit doctor     # all-green or actionable findings

# Bring up the stack
docker compose up -d

# (optional) public HTTPS reverse proxy
docker compose --profile public up -d

Open http://localhost:8123 (HA), http://localhost:4000 (TeslaMate), http://localhost:3000 (Grafana).

Architecture

                       Tesla (mobile)
                         │
                         │ Fleet API
                         ▼
                ┌────────────────────┐
                │ Tesla HTTP Proxy   │ signs commands per teslamotors/vehicle-command
                │ (port 4443)        │
                └────────┬───────────┘
                         │
   ┌─────────────────────┼──────────────┐
   │                     │              │
   ▼                     ▼              ▼
HA tesla_fleet        TeslaMate     Hey-Nabu MCP
integration         (drives + BH)   (sibling repo)
   │                     │
   └─────────┬───────────┘
             │ events / state
             ▼
        Mosquitto MQTT broker  ◄────  tesla_ble_mqtt (BLE bridge to car)
             │
             ▼
       Home Assistant ──► Caddy ──► Public HTTPS (optional)
       (port 8123)        (443)

See docs/architecture.md for the full diagram and per-component rationale.

Sharp edges

The wave-3 spec flagged several known footguns. The most important one is documented in docs/sharp-edges.md: llamafilm/tesla-http-proxy-addon is unmaintained as of January 2025 (the maintainer sold their Tesla). teslakit deliberately ships the upstream tesla/vehicle-command container directly rather than the orphaned HA add-on. If you've previously used the add-on and want to migrate, see the doc.

License

AGPL-3.0-or-later. teslakit depends on TeslaMate v3.0.0+ which switched MIT → AGPLv3 in February 2026. We match. If you fork teslakit and host it as a network service, you must release modifications under AGPLv3. Your private at-home use is unaffected.

CI

GitHub Actions runs ruff + pytest on Python 3.12 and 3.13, plus a docker compose config lint of docker-compose.yml, on every push and PR. See .github/workflows/ci.yml. End-to-end docker-compose smoke (real HA / TeslaMate / Postgres containers) is intentionally out of scope for CI.