Skip to main content

teslakit

PyPI version Python versions License: AGPL v3 ci

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

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.

Metadata

Release files for teslakit 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for teslakit 0.1.0
File Size Uploaded Provenance Actions
teslakit-0.1.0.tar.gz 12.9 kB Without provenance Details for teslakit-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for teslakit 0.1.0
File Interpreter ABI Platform Actions
teslakit-0.1.0-py3-none-any.whl Python 3 none any Details for teslakit-0.1.0-py3-none-any.whl

Total release size: 26.1 kB

Release files / teslakit-0.1.0.tar.gz

Download URL teslakit-0.1.0.tar.gz
Size 12.9 kB
Tags Source
SHA-256 checksum
How to use checksums
4d7f15a90abf08853cb6e82615d96a05d8805aabe590b7cbf995c0e5607ff82d
BLAKE2b-256 checksum
How to use checksums
4a66b3f96dab4b9cf56b9baa48a50507ec334f2d2e07a4178136a08076d26441
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.11.12 {"installer":{"name":"uv","version":"0.11.12","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":null,"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Release files / teslakit-0.1.0-py3-none-any.whl

Download URL teslakit-0.1.0-py3-none-any.whl
Size 13.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
37bc3670a90661449cc1080d2e741295bf228641408e71d80d3dda44e983bd3a
BLAKE2b-256 checksum
How to use checksums
8e79d60f485eda559e71fcca977d74fb8b0dd011b318dc3b91e8b6fc0cd7e297
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.11.12 {"installer":{"name":"uv","version":"0.11.12","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":null,"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Security for teslakit 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page