Metadata-Version: 2.4
Name: teslakit
Version: 0.1.0
Summary: Self-host the Tessie experience: Docker Compose for HA + TeslaMate + Tesla HTTP Proxy + BLE.
Project-URL: Homepage, https://github.com/Raymondriter/teslakit
Project-URL: Repository, https://github.com/Raymondriter/teslakit
Project-URL: Issues, https://github.com/Raymondriter/teslakit/issues
Project-URL: Changelog, https://github.com/Raymondriter/teslakit/blob/main/CHANGELOG.md
Author-email: Raymondriter <tenzinshare@gmail.com>
License: AGPL-3.0-or-later
License-File: LICENSE
Keywords: docker-compose,fleet-api,ha-supervisor,home-assistant,mqtt,nginx,self-host,tesla,teslamate,tessie
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: End Users/Desktop
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Home Automation
Classifier: Topic :: System :: Installation/Setup
Requires-Python: >=3.12
Requires-Dist: httpx>=0.27
Requires-Dist: platformdirs>=4.0
Requires-Dist: pydantic>=2.7
Requires-Dist: pyyaml>=6.0
Requires-Dist: questionary>=2.0
Requires-Dist: rich>=13.7
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.7; extra == 'dev'
Description-Content-Type: text/markdown

# teslakit

[![PyPI version](https://img.shields.io/pypi/v/teslakit.svg)](https://pypi.org/project/teslakit/)
[![Python versions](https://img.shields.io/pypi/pyversions/teslakit.svg)](https://pypi.org/project/teslakit/)
[![License: AGPL v3](https://img.shields.io/badge/license-AGPL--3.0--or--later-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)
[![ci](https://github.com/Raymondriter/teslakit/actions/workflows/ci.yml/badge.svg)](https://github.com/Raymondriter/teslakit/actions/workflows/ci.yml)

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:

```bash
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:

```bash
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`](RELEASE.md) for why the Compose file
isn't shipped inside the wheel.

**License: [AGPL-3.0-or-later](#license)** — 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`](../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](../hey-nabu-climate-concierge))
- **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

```bash
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`](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`](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](https://github.com/Raymondriter/teslakit/actions/workflows/ci.yml/badge.svg)](https://github.com/Raymondriter/teslakit/actions/workflows/ci.yml)

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`](.github/workflows/ci.yml). End-to-end docker-compose smoke (real HA / TeslaMate / Postgres containers) is intentionally out of scope for CI.
