Skip to content

Hosted cloud sync

The hosted cloud is under active development and not open for sign-up yet. Everything below describes the behaviour you get when you point your device at a server running the current code — including the dashboard UI this page documents.

The hosted cloud is an optional companion service for the bark monitor. Your device keeps working exactly as before — recording, bots, local files — and in addition pushes its events to the cloud, which mirrors them and shows a dashboard with the history.

The defining property: the cloud is a verified mirror, never the source of truth. All pushes are one-way (device → cloud). If the cloud is down, or you cancel it, or you never had it: your recording.db is unaffected and remains complete.

What is synced

  • Bark, activity and recording start/stop events — everything in the event store (see where your data lives). Day totals shown on the dashboard are derived from these events.
  • Audio recordings are never uploaded. Audio upload is a separate, opt-in consent per device (off by default) and is not active yet.
  • The cloud re-computes the hash chain of every batch it receives: a tampered or corrupted push is rejected, not silently stored.

Pairing a device

Each device is paired once with an 8-character pairing code:

  1. On the dashboard, create a device. You get a pairing code.
  2. On the device, run:
bark-monitor-cloud-pair \
    --config-file path/to/parameters.json \
    --server-url https://cloud.example.com \
    --pairing-code ABC23456

This exchanges the one-time code for a long-lived device token and saves it in your config file under cloud_parameters. Re-running the command re-pairs (useful after a reinstall: a stable machine id stored next to the config makes the device map back to the same cloud device).

Enabling the sync

With cloud_parameters containing a server_url and a device_token in the config file, the cloud sync is active. It combines with the other sync options: you can keep your Nextcloud backup and push to the hosted cloud at the same time.

Failures are non-fatal by design: if the cloud is unreachable, the events stay on the device and are pushed later (the device remembers what the cloud last acknowledged). Cloud problems never interrupt the monitoring itself.

The server side (what you see at the server_url) is the cloud dashboard: a sign-in-by-email web app showing today's barking, history charts, and the paired devices. See the dashboard README in cloud/dashboard/ for what it looks like.

Running your own server

The server is a small FastAPI app (package bark-monitor-cloud). To try it locally:

uv sync --package bark-monitor-cloud
python -m bark_monitor_cloud            # serves 127.0.0.1:8000
python -m bark_monitor_cloud 0.0.0.0 8080  # custom host/port

The PORT environment variable is honoured as the default port (handy for PaaS deploys). uvicorn bark_monitor_cloud.main:app works too.

Environment variables

Variable Meaning Default
BARK_CLOUD_SECRET_KEY JWT signing key for sessions unset: random per process
BARK_CLOUD_DATABASE_PATH SQLite file location bark_monitor_cloud.db
BARK_CLOUD_SMTP_URL SMTP relay for magic links, smtp://user:pass@host:587 unset: link printed to server log
BARK_CLOUD_SMTP_FROM From: address for the emails bark monitor <noreply@…>
BARK_CLOUD_BASE_URL Origin for links in emails unset: request host
BARK_CLOUD_FORWARDED_ALLOW_IPS Proxy trust for X-Forwarded-For unset

BARK_CLOUD_SMTP_URL picks its TLS mode from the port and an optional ?tls= query: starttls on 587 (default), ssl on 465, ?tls=none for a local relay.

Signing in (dev)

There are no passwords: enter your email, and the server delivers a one-time link. Without BARK_CLOUD_SMTP_URL the "delivery" is a line in the server terminal:

[magic-link] you@example.com: http://127.0.0.1:8000/#/verify?token=…

Paste it into a browser and you are signed in. Each link works once and expires after 30 minutes. With SMTP configured the same link arrives by email and the dashboard says so.

The dashboard itself is a separate Vite dev server while hacking on the UI (npm run dev inside cloud/dashboard/, proxying API calls to 127.0.0.1:8000) — details in the dashboard README.

Secrets and sessions

Session tokens are JWTs signed with BARK_CLOUD_SECRET_KEY. Without it, a random key is generated once per process: sessions work fine but everyone signs in again after a restart (and each worker in a multi-worker deployment would need it set, or they would each mint their own key — so production must set it):

export BARK_CLOUD_SECRET_KEY=$(openssl rand -hex 32)

Demo data

cloud/scripts/seed_demo_data.py fills an account with three weeks of realistic, hash-chain-verified events through the real API (magic link, device pairing, verified ingest) — the same bytes a Raspberry Pi would push:

uv run --package bark-monitor-cloud python cloud/scripts/seed_demo_data.py \
    --email test@bark.com --db bark_monitor_cloud.db

Then sign in from the dashboard with that email. Re-running wipes and re-seeds the account's devices. There is also a full-API smoke journey in cloud/scripts/e2e_dashboard.py (shell served, sign-in, device, push, dashboard reads).

Deleting your data

Deleting a device on the dashboard deletes every event mirrored for it, and resets the pairing. Since the device is the source of truth, a device that pushes again afterwards starts a fresh history on the cloud (nothing is "restored" from the local store beyond what is recorded after the deletion).