Source repository for the Vector Home Assistant OS addon. The addon is distributed via twiebe/hassos-addons.
Vector is a high-performance observability data pipeline. This addon runs Vector as a Home Assistant OS service, collecting logs from the systemd journal and forwarding them to a configured sink.
On startup the addon generates a Vector configuration from your addon options and starts the Vector process. The generated configuration is printed to the addon log at startup (with credentials obfuscated) so you can verify it without needing shell access.
Logs are collected from the systemd journal (journald), which on Home Assistant OS includes all system services, the supervisor, and any Docker containers running as addons.
Two optional transforms can be applied before logs are forwarded:
Normalises all field names to lowercase. Journald emits many fields in uppercase (e.g. CONTAINER_NAME, _SYSTEMD_UNIT). Enabling this makes field names consistent and easier to work with in most log backends.
Vector's journald source attaches the hostname under the field host. If your log backend or query conventions expect a different name (e.g. hostname), enable this transform and set the desired field name.
The two transforms are independent and can be combined. When both are enabled, lowercase is applied first, then the host field is renamed.
Endpoint URLs must include an explicit http:// or https:// scheme. An endpoint that is empty or has no scheme fails startup with an error in the addon log rather than being silently completed with a default.
VictoriaLogs exposes an Elasticsearch-compatible bulk ingest API, which is what Vector uses under the hood — the sink type in Vector's config is elasticsearch, but the addon models this honestly as victorialogs since the configuration (in particular the query parameters) is specific to VictoriaLogs and not portable to plain Elasticsearch or OpenSearch.
The following VictoriaLogs-specific query parameters are always set in the generated config:
| Parameter | Value | Purpose |
|---|---|---|
_msg_field |
message |
Tells VictoriaLogs which field contains the log message |
_time_field |
timestamp |
Tells VictoriaLogs which field contains the timestamp |
_stream_fields |
auto or configured | Fields used to group logs into streams |
_stream_fields is auto-generated based on the active transforms: it uses the host field name (as renamed, if applicable) and container_name or CONTAINER_NAME depending on whether lowercase is enabled. You can override this by setting the Stream Fields option explicitly.
Compression is fixed at gzip and the Elasticsearch healthcheck is disabled — VictoriaLogs does not expose that endpoint.
| Option | Description |
|---|---|
| Endpoint URL | Full URL of your VictoriaLogs ingest endpoint |
| Auth Username | Basic auth username (leave empty to disable) |
| Auth Password | Basic auth password |
| Stream Fields | Override the auto-generated _stream_fields value |
| Ignore Fields | Comma-separated list of fields to drop before forwarding (e.g. log.offset,event.original) |
Loki is supported via Vector's native loki sink. This includes Grafana Cloud hosted Loki.
Stream labels are auto-generated from the active transforms using the same logic as VictoriaLogs stream fields: the host field name and container_name / CONTAINER_NAME depending on whether lowercase is enabled. Fields used as labels are removed from the log body to avoid duplication. Compression is fixed at gzip.
| Option | Description |
|---|---|
| Endpoint URL | Full URL of your Loki endpoint (e.g. https://logs-prod-us-central1.grafana.net) |
| Auth Username | Basic auth username — for Grafana Cloud this is your numeric org ID |
| Auth Password | Basic auth password — for Grafana Cloud this is your API token |
| Tenant ID | Sets the X-Scope-OrgID header — required for Grafana Cloud and multi-tenant Loki deployments |
| Encoding | Log body encoding: text (the message field only) or json (full structured event) |
For use cases not covered by the addon options, you can supply a handwritten Vector configuration file. Enable Override Config and set Override Config Path to the path of your file (default: vector.yaml).
The override file lives in the addon's own config directory, which Home Assistant mounts from /addon_configs/{repo}_vector/ on the host. You can manage files there via the Samba addon or the Studio Code Server addon.
Override Config Path is resolved relative to that directory, so the default vector.yaml refers to /addon_configs/{repo}_vector/vector.yaml — just drop the file in and go. A subdirectory works too (e.g. conf/vector.yaml). For backwards compatibility an absolute path is also accepted and used verbatim; the addon config dir is mounted at /config inside the container, so the previous default /config/vector.yaml continues to point at the same file.
When override mode is active, all other addon options are ignored entirely — the addon copies your file directly to the Vector config location and starts Vector with it. The generated config is not written and no transforms are applied. The override file is still printed to the addon log at startup (with passwords obfuscated).
This is useful when you need additional inputs, complex routing, or full control over the Vector topology.
The override file must be a valid Vector configuration file.
main holds released code, dev is where development happens. Renovate opens its PRs against dev.
Every push to dev builds images tagged dev and dev-<short sha> and pushes them to GHCR. The workflow then sets version: "dev-<short sha>" in vector-dev/config.yaml of twiebe/hassos-addons. Home Assistant installations with the Vector (dev) addon offer this as a regular update. That step needs a HASSOS_ADDONS_PAT secret in this repo: a token with contents write access to hassos-addons. Without it the step is skipped, and make dev-bump in hassos-addons does the same by hand.
Pushing a version tag (e.g. 0.8.0) builds the release images tagged with that version.
tests/e2e/run.sh runs a real Home Assistant Supervisor, installs this addon built from the working tree as a local addon, and checks that logs arrive in VictoriaLogs and Loki. Each directory under tests/e2e/cases/ is one test case: addon options, the backend, and what must arrive. Adding a case needs no script changes.
The workflow e2e.yml runs it on amd64 and aarch64 for pull requests against dev, pushes to dev and on manual dispatch. make release requires that run to be green.
The script needs Linux with systemd, journald, dbus and Docker, and runs as root. It switches Docker's log driver to journald and enables the persistent journal, and does not undo either. Use a dedicated host, such as a CI runner or a throwaway VM. Basic auth is not covered.
On a Mac with OrbStack, use an isolated Linux machine. The plain OrbStack Docker engine has no systemd. Set the machine up once:
orb create --isolated ubuntu ha-e2e
orb -m ha-e2e -u root sh -c 'apt-get update && apt-get install -y docker.io jq curl fuse-overlayfs &&
echo "{\"storage-driver\": \"fuse-overlayfs\", \"features\": {\"containerd-snapshotter\": false}}" > /etc/docker/daemon.json &&
systemctl restart docker'The machine's overlayfs cannot rename directories across layers, which breaks dpkg in the addon build, so Docker uses fuse-overlayfs there. An isolated machine does not see your Mac files, so copy the repo in and run the tests from the repo root:
tar --exclude .git -cf - . | orb -m ha-e2e -u root sh -c 'rm -rf /root/addon && mkdir /root/addon && tar -C /root/addon -xf -'
orb -m ha-e2e -u root sh -c 'cd /root/addon && tests/e2e/run.sh'Inside an OrbStack machine the Supervisor reports the system as unhealthy (privileged) and its plugins cannot start. The script ignores that health check and stands in for the DNS plugin with CoreDNS. On a CI runner neither happens.
Environment variables:
| Variable | Effect |
|---|---|
HASSOS_ADDONS_DIR |
Take config.yaml and translations/ from this hassos-addons checkout instead of its main branch on GitHub, e.g. to test a schema change before pushing it |
CASES |
Run only the cases matching this glob, e.g. CASES='loki-*' |
KEEP=1 |
Leave all containers and the Supervisor data dir in place after the run, for debugging. The next run still starts clean |
E2E_DATA |
Supervisor data dir, default /tmp/supervisor-e2e |
E2E_REPORT |
Append the ACK/NACK protocol as a Markdown table to this file. CI uses the job summary |
- Add release notes to
hassos-addons/vector-dev/CHANGELOG.mdunder## <version>and push them tomain. - Here, run
make release(needs an authenticatedgh). It first waits for the E2E run on the tip ofdevand stops if it is missing or red, before anything is tagged or pushed. It reads that changelog section fromhassos-addonsmainand fails if it is missing or empty. Then it fast-forwardsmaintodev, creates an annotated tag with the section as message, pushes, waits for the release images and creates the GitHub release with the tag message as description. - In
hassos-addons, runmake release VERSION=<version>. It copiesvector-dev/tovector/, sets the version and commits.
The version defaults to the next minor after the latest tag. Override it with VERSION=x.y.z. make lists all targets.