README
¶
Rivolt
A real Rivian companion. Live telemetry, per-trip analytics, a real charging cost ledger, and a route planner that tells you what a road trip will actually cost.
Rivolt is an open-source companion app for Rivian vehicles. It streams live telemetry from your truck, records every drive and charging session against your real electricity rate, and plans road trips with cost / weather / efficiency analysis built in.
The official Rivian app shows you numbers; Rivolt turns them into a ledger you own and a planner that actually accounts for what the trip will cost.
Overview — see your truck at a glance
The home view stitches together what you actually care about right now: current SoC and range, where the truck is, whether it's plugged in, the most recent drive, the most recent charge, and the rolling weekly totals (miles, kWh, $).
Live — real-time telemetry
The Live page subscribes to Rivian's WebSocket feed and renders 1–5 s frames while you're driving (~30 s when parked). SoC, range, gear, drive mode, charger state, inside / outside temp, tire pressures, and the GPS dot all move in real time. Useful in the passenger seat to verify a route, or from the kitchen to see if the truck actually started charging when you plugged it in.
Drives — every trip explained
The Drives page lists every recorded drive with distance, duration, average speed, energy used, cost, and a route preview. Click in to land on the per-drive detail: the map is road-snapped (OSRM or Valhalla) and coloured by speed — gray for parking-lot crawls, rose for interstate — over a Protomaps basemap. Below the map, time-aligned charts for speed, SoC, elevation, temperature, headwind, and precipitation; weather context for the drive's start hour pulled from Open-Meteo when enabled.
A "Low GPS accuracy" pill surfaces when the Rivian modem returned stale fixes or implausible jumps during the drive, with thresholds that are admin-tunable so the warning doesn't fire on every parking garage.
Charges — every kWh, every dollar
The Charges page lists every charging session — date, location, energy delivered, peak kW, total cost. Click in for the full detail: power curve over time, peak and average kW, energy delivered, session duration, and — when the Parallax feed is available — the thermal split between energy going to the pack and energy spent on battery conditioning.
Sessions are automatically bucketed Home / Public / DCFC by
DBSCAN clustering on coordinates and peak kW; sessions in your
home cluster price against your configured home rate, sessions
out in the wild price against the session's actual reported cost
when Rivian provides it.
Trip planner — plan with cost in mind
This is the feature the app was built for. Pick origin, destination, optional via-stops, and a departure date/time on the calendar. Rivolt asks Rivian's own planner to lay out a route with charging stops, then layers on top of it:
- A self-hosted Protomaps basemap with the actual route drawn in.
- A charger overlay along the route corridor — perpendicular distance to the polyline, not bounding box, with arc-length trimming near the endpoints so the destination metro doesn't drag in dozens of irrelevant downtown stations.
- DCFC / L2 / All toggle on the charger overlay, sourced from NREL AFDC data with proper DCFC vs L2 discrimination (Tesla Destination chargers no longer mis-classified as Supercharger).
- Last-trip persistence — closing and reopening lands you back on yesterday's setup.
- Departure-time-aware arrival clock: the table shows arrival HH:MM at every stop based on your chosen departure, not "now".
Trip analysis — what the trip actually costs
After the route comes back, the Trip analysis card breaks it down. The dollar figures are computed deterministically in Go — not asked of an LLM — from your home rate, stop SoC deltas, and an industry-default DCFC rate:
- DCFC spend — what you'll actually pay at fast chargers along the way.
- Home-rate equivalent — what the total energy used would have cost if every kWh came from your home meter; useful as a "what is this trip actually costing me" baseline.
Around those numbers, when an AI provider is wired by the operator, the model writes short categorised commentary across Cost, Efficiency (drive mode, departure timing), Weather (only when there's something material — cold-snap, headwind > 15 kph, precipitation), and Vehicle (tire pressures, pack size, adapter dependency at any stop). Empty categories hide their headers.
Settings — everything in one place
A five-tab layout for the per-user controls:
- Account — Rivian connection (with the dedicated
Authorized Driver pattern documented in
docs/SIGNUP.md). - Vehicle — vehicle profile (pack capacity), display units, home location.
- Charging — home $/kWh rate + currency, preferred public networks, trip planner defaults.
- Notifications — per-device push subscription with per-event toggles (see below).
- Data — ElectraFi CSV import + danger zone (full JSON backup, reset).
Notifications — push that actually fires
Web Push (VAPID), per-device subscribe. Enable once on each device you want pinged, pick which events you care about, and Rivolt delivers an OS-level notification on the next matching event. Currently wired: charging session completes (with the final SoC + kWh added in the body). Plug-in reminders and anomaly alerts have the plumbing — event sources land next.
Sign up
See docs/SIGNUP.md for an end-to-end walkthrough
of:
- requesting beta access and finishing signup from the one-click email link an admin sends,
- connecting your Rivian account (with the dedicated Authorized Driver account approach we recommend),
- importing your history from ElectraFi,
- configuring your home charging cost,
- planning your first trip.
Data ownership
- Your Rivian credentials are AES-GCM sealed and decrypted only in-memory at request time. Disconnect Rivian in one click.
- AI features (when enabled by the operator) are powered by an install-wide provider — OpenAI, Anthropic, or Google Gemini — configured from the admin UI. Each user's drive / trip context is sent to that provider only at the moment a recap or trip analysis is generated; nothing is mirrored to a third-party service in between.
- All your drive, charge, and trip data is exportable as JSON from Settings → Data, and deletable from the same page.
- Read-only against the Rivian API. Rivolt sends commands to no Rivian endpoint, period. It can't unlock doors, start charging, or change drive mode. Telemetry only.
Stack
- Single Go binary + embedded SPA. Distroless multi-arch container image; the same binary serves API + static assets.
- Go 1.25, chi router, pgx-backed
database/sql, coder/websocket for the Rivian feed, webpush-go for VAPID. - Postgres with Row-Level Security, monthly partitioning on
vehicle_state, envelope-encrypted secrets inuser_secrets. Multi-tenant from day one: every data-plane store carriesuser_id, every query filters on it, every request pinsapp.user_idso RLS does the final enforcement at the DB. - React 18 + TypeScript + Vite + Tailwind v3 for the SPA; TanStack Query for the data layer; uPlot for time-series charts; Leaflet + protomaps-leaflet for maps.
- Optional AI providers — OpenAI, Anthropic, or Google Gemini, selected install-wide by the operator from the admin UI. Hot-swappable; calls go to the chosen provider only when an AI feature actually runs (trip analysis, drive recap).
Status
In production at rivolt.dev. Preview at
preview.rivolt.dev tracks main.
See docs/ROADMAP.md for what's queued and
docs/ARCHITECTURE.md for the load-bearing
design decisions.
License
Core is MIT-licensed. Some future add-ons may ship under a separate commercial license; details will be published alongside each add-on.
Legal
"Rivian" is a trademark of Rivian Automotive, Inc. Rivolt is an independent, community-built project with no affiliation to, endorsement by, or partnership with Rivian. Reference to Rivian is for descriptive purposes only.
Use at your own risk. Rivolt relies on unofficial access to Rivian's APIs and may break at any time.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
rivolt
command
Command rivolt is the single-binary server for the Rivolt Rivian companion.
|
Command rivolt is the single-binary server for the Rivolt Rivian companion. |
|
internal
|
|
|
ai
Package ai hosts the hot-swappable LLM provider adapters (OpenAI, Anthropic, Google Gemini) used across Rivolt: weekly digest, trip planning, charging strategy, and anomaly explanations.
|
Package ai hosts the hot-swappable LLM provider adapters (OpenAI, Anthropic, Google Gemini) used across Rivolt: weekly digest, trip planning, charging strategy, and anomaly explanations. |
|
analytics
Package analytics hosts local, deterministic analyses over the user's driving and charging history.
|
Package analytics hosts local, deterministic analyses over the user's driving and charging history. |
|
api
Package api wires the HTTP surface for Rivolt.
|
Package api wires the HTTP surface for Rivolt. |
|
appsettings
Package appsettings is the install-wide key/value store backing the AI provider configuration (and any future install-scoped setting).
|
Package appsettings is the install-wide key/value store backing the AI provider configuration (and any future install-scoped setting). |
|
auth
Package auth owns Rivolt's session-level authentication: the /api/auth/* endpoints, the cookie format, and the middleware that resolves an authenticated user into request context.
|
Package auth owns Rivolt's session-level authentication: the /api/auth/* endpoints, the cookie format, and the middleware that resolves an authenticated user into request context. |
|
charges
Package charges persists derived charge sessions.
|
Package charges persists derived charge sessions. |
|
config
Package config holds runtime configuration for rivolt.
|
Package config holds runtime configuration for rivolt. |
|
crypto
Package crypto is Rivolt's in-process key-wrapping layer.
|
Package crypto is Rivolt's in-process key-wrapping layer. |
|
db
Package db owns the Rivolt Postgres connection pool, the shared migration runner, and a handful of identity helpers used by every store.
|
Package db owns the Rivolt Postgres connection pool, the shared migration runner, and a handful of identity helpers used by every store. |
|
dcfcrates
Package dcfcrates owns the DCFC network table used by trip planning.
|
Package dcfcrates owns the DCFC network table used by trip planning. |
|
drives
Package drives persists derived drive sessions.
|
Package drives persists derived drive sessions. |
|
electrafi
Package electrafi imports TeslaFi / ElectraFi polling-dump CSV files into Rivolt's drives and charges stores.
|
Package electrafi imports TeslaFi / ElectraFi polling-dump CSV files into Rivolt's drives and charges stores. |
|
elevation
Package elevation looks up altitude (meters above sea level) for arbitrary lat/lon coordinates against the Mapzen Terrarium DEM (https://github.com/tilezen/joerd/blob/master/docs/formats.md#terrarium).
|
Package elevation looks up altitude (meters above sea level) for arbitrary lat/lon coordinates against the Mapzen Terrarium DEM (https://github.com/tilezen/joerd/blob/master/docs/formats.md#terrarium). |
|
email
Package email sends transactional mail via the Resend HTTP API.
|
Package email sends transactional mail via the Resend HTTP API. |
|
flags
Package flags owns the DB-backed operational flag table (migration 0003_flags.sql).
|
Package flags owns the DB-backed operational flag table (migration 0003_flags.sql). |
|
geocoding
Package geocoding wraps Open-Meteo's free geocoding endpoint (https://geocoding-api.open-meteo.com/v1/search) for forward- geocoding text input → lat/lon.
|
Package geocoding wraps Open-Meteo's free geocoding endpoint (https://geocoding-api.open-meteo.com/v1/search) for forward- geocoding text input → lat/lon. |
|
hydra
Package hydra is a thin admin-API client for Ory Hydra.
|
Package hydra is a thin admin-API client for Ory Hydra. |
|
idp
Package idp defines the UserProvider interface — the single contract between Rivolt's API layer and whichever identity backend is deployed.
|
Package idp defines the UserProvider interface — the single contract between Rivolt's API layer and whichever identity backend is deployed. |
|
kratos
Package kratos provides admin-side provisioning of Ory Kratos identities via the Kratos admin API.
|
Package kratos provides admin-side provisioning of Ory Kratos identities via the Kratos admin API. |
|
leases
Package leases coordinates per-vehicle ownership across multiple rivolt pods so each vehicle is subscribed by exactly one process.
|
Package leases coordinates per-vehicle ownership across multiple rivolt pods so each vehicle is subscribed by exactly one process. |
|
logging
Package logging provides a context-aware slog handler and helpers for stamping per-request fields (request_id, user_id, vehicle_id, trace_id) onto every log line emitted while serving a request, without requiring callers to thread the logger through.
|
Package logging provides a context-aware slog handler and helpers for stamping per-request fields (request_id, user_id, vehicle_id, trace_id) onto every log line emitted while serving a request, without requiring callers to thread the logger through. |
|
maps
Package maps wires same-origin reverse-proxies that let the SPA reach self-hosted map services (Valhalla for routing + map matching, an nginx-served PMTiles bundle for vector basemaps) through the existing rivolt origin and session cookie.
|
Package maps wires same-origin reverse-proxies that let the SPA reach self-hosted map services (Valhalla for routing + map matching, an nginx-served PMTiles bundle for vector basemaps) through the existing rivolt origin and session cookie. |
|
metrics
Package metrics owns the application's Prometheus instrumentation.
|
Package metrics owns the application's Prometheus instrumentation. |
|
oidc
Package oidc adds an OIDC sign-in path alongside the static operator credential and the trusted-proxy header in internal/auth.
|
Package oidc adds an OIDC sign-in path alongside the static operator credential and the trusted-proxy header in internal/auth. |
|
push
Package push handles Web Push subscriptions and notification delivery.
|
Package push handles Web Push subscriptions and notification delivery. |
|
ratelimit
Package ratelimit implements the global upstream token bucket gating outbound calls to Rivian's GraphQL gateway.
|
Package ratelimit implements the global upstream token bucket gating outbound calls to Rivian's GraphQL gateway. |
|
recap
Package recap turns a finished drive into a short natural-language narration ("Trip recap") via the operator-configured LLM provider.
|
Package recap turns a finished drive into a short natural-language narration ("Trip recap") via the operator-configured LLM provider. |
|
rivian
Package rivian is Rivolt's adapter to the unofficial Rivian owner-app GraphQL API.
|
Package rivian is Rivolt's adapter to the unofficial Rivian owner-app GraphQL API. |
|
samples
Package samples persists raw vehicle_state polling snapshots.
|
Package samples persists raw vehicle_state polling snapshots. |
|
secrets
Package secrets is the persistence layer on top of [`internal/crypto`](../crypto).
|
Package secrets is the persistence layer on top of [`internal/crypto`](../crypto). |
|
sessions
Package sessions is the source-of-truth store for authenticated user sessions.
|
Package sessions is the source-of-truth store for authenticated user sessions. |
|
settings
Package settings persists app-level configuration (AI provider keys, charging cost, Rivian session) in the shared Postgres database.
|
Package settings persists app-level configuration (AI provider keys, charging cost, Rivian session) in the shared Postgres database. |
|
signuprequests
Package signuprequests manages the pre-account waitlist: someone visits /signup without an invite, fills the "request access" form, and lands as a pending row that an admin later approves (minting a single-use magic-link signup token) or rejects.
|
Package signuprequests manages the pre-account waitlist: someone visits /signup without an invite, fills the "request access" form, and lands as a pending row that an admin later approves (minting a single-use magic-link signup token) or rejects. |
|
tracing
Package tracing wires the OpenTelemetry trace SDK with an OTLP/HTTP exporter pointed at Grafana Tempo.
|
Package tracing wires the OpenTelemetry trace SDK with an OTLP/HTTP exporter pointed at Grafana Tempo. |
|
tripadvice
Package tripadvice wraps the operator-configured AI provider to generate plain-language observations about a Rivian trip plan: charging stop summary, arrival SoC commentary, adapter warnings, and drive-mode suggestions when the plan looks sub-optimal.
|
Package tripadvice wraps the operator-configured AI provider to generate plain-language observations about a Rivian trip plan: charging stop summary, arrival SoC commentary, adapter warnings, and drive-mode suggestions when the plan looks sub-optimal. |
|
tripprofile
Package tripprofile derives an energy-consumption multiplier from a user's editable VehicleProfile (wheel size, tire type, roof / rear accessories, default cargo).
|
Package tripprofile derives an energy-consumption multiplier from a user's editable VehicleProfile (wheel size, tire type, roof / rear accessories, default cargo). |
|
trips
Package trips persists per-user named trip templates for the planner.
|
Package trips persists per-user named trip templates for the planner. |
|
tripweather
Package tripweather corrects a Rivian trip plan's per-waypoint SoC curve for weather conditions Rivian's planner doesn't see.
|
Package tripweather corrects a Rivian trip plan's per-waypoint SoC curve for weather conditions Rivian's planner doesn't see. |
|
weather
Package weather enriches a drive with the conditions at its start point and time.
|
Package weather enriches a drive with the conditions at its start point and time. |
|
web
Package web embeds the built Vite web app into the Go binary.
|
Package web embeds the built Vite web app into the Go binary. |