Beacon

Securely reach and monitor every machine you run — from one binary. No open ports, and nothing sensitive ever leaves your box.

---

You run things on machines you don't always sit in front of — Home Assistant on a Pi, a NAS, Pi-hole, Grafana, your own apps on an N100 or a VPS, a client's server. Beacon does two things first: it gives you secure remote access to those machines and the services on them — with no open ports — and it monitors their health and alerts you when something breaks. It's workload-agnostic: it reaches and watches whatever is on the box, not just things it deployed. (It can run your deploys too, but access and monitoring are the core.)

And it's built on a strict local-first, zero-trust model — your code, secrets, and data never leave the box, and no cloud ever holds root on your machines.

⬡ beacon v0.3.2  ● running  pid 1847  uptime 14d 3h

DEVICE  pi-homelab  192.168.1.42  arm64  Debian 12

SYSTEM  cpu 12% ████░░░░░░░░░░░░  mem 67% ██████████░░░░░░  disk 41% ██████░░░░░░░░░░
        load 0.42 0.38 0.35  temp 48°C

PROJECTS  3 healthy  1 warning  0 down

  ● portfolio-site      v2.1.0   deployed 2h ago    3/3 checks passing
  ● home-assistant      v2024.3  deployed 5d ago    2/2 checks passing
  ◐ nextcloud           v28.0.1  deployed 3d ago    2/3 checks passing
    └─ ⚠ HTTP https://cloud.local/status  timeout 5.2s > 3s threshold

That's beacon status. There's also a browser dashboard at http://localhost:9100 — self-contained, no CDN, works offline.

---

✨ What Beacon does

Two things first — secure remote access and monitoring — on a zero-trust foundation. Everything else is a bonus.

🔐 Built zero-trust, local-first

This is the part that matters before any feature:

• No open ports. Tunnels connect outbound from your device — nothing is exposed to the internet, and it works behind CGNAT.
• No control plane with root. The optional cloud can never log in to your machine on its own; it only relays commands you authorized, and the agent runs them.
• Nothing sensitive leaves the box. Your source code, deploy scripts, tokens, and secrets stay local. The cloud only ever sees the metrics and log lines you explicitly choose to send.
• Works offline. The agent and its dashboard run fully local, with no account.

🌐 Remote access

• Reach any service, no open ports — securely reach Home Assistant, Grafana, Jellyfin, a NAS admin page, Pi-hole, or any local HTTP service from anywhere. No dynamic DNS, no Nabu Casa, no Cloudflare account or managed domain. Authenticated with short-lived tokens; only you can reach your services.
• Remote terminal — open a shell on your device from the browser. No SSH port, no VPN. The cloud relays a PTY session between your browser and the agent.
• Device-verified gate (recommended) — enroll a passkey (preferred) or set a passphrase (fallback) so a second factor is required before any remote terminal or tunnel session can open. It's verified on the device — BeaconInfra only relays. The passkey's private key never enters the page, and you can layer on an authenticator-app (TOTP) code so the cloud can't silently open a session. See Securing remote access.

📊 Monitoring & alerts

• Health & metrics — health checks (HTTP, port, command), CPU/memory/disk/temperature, per-project status, Prometheus metrics.
• Alerts — via webhook (Slack, Discord) or SMTP, with quiet hours and offline-device detection.
• Log forwarding — tail log files, Docker container logs, or journalctl and forward them to the dashboard, filtered so you only ship what matters.

🧰 Also

• Deploy automation (bring your own script) — Beacon doesn't replace your stack or turn your box into a PaaS. Point it at a Git repo or Docker registry; it watches for new tags, injects your secrets, and runs your deploy script. Push a tag, walk away.
• WireGuard VPN — turn any Beacon device into a peer-to-peer WireGuard exit node and route traffic through your home network from a laptop.

BeaconInfra is the optional cloud that adds the multi-device dashboard, tunnels, and remote terminal. When an API key is configured, beacon start sends periodic heartbeats with device metrics and project health; the cloud uses these to power the dashboard, detect offline devices, and relay commands back to the agent. Everything except tunnels and remote terminal works without an account.

---

🧩 One layer across every machine

Beacon isn't a PaaS and doesn't replace how you deploy. It's the operations layer across all your machines — the box running your apps and the Home Assistant box, the NAS, the Pis, the client server, the VPS you never containerized — so you reach, watch, and fix every one of them from a single place, without handing any cloud root over your hardware.

---

🏠 Access Home Assistant from anywhere

If you run Home Assistant OS, the primary path is the Beacon Home Assistant add-on: install the add-on, paste your BeaconInfra API key, enable tunnel_home_assistant, and start it. The add-on points the tunnel at Home Assistant Core on http://homeassistant:8123.

If you run Beacon on a normal Linux host or in Docker next to Home Assistant, use the CLI tunnel flow. Three commands, no port-forwarding, no Nabu Casa.

# 1. Log in to BeaconInfra (free account)
beacon cloud login --api-key usr_xxxxxxxx

# 2. Expose Home Assistant
beacon tunnel add homeassistant --port 8123
# Or, for Docker Compose / HA OS style service DNS:
# beacon tunnel add homeassistant --port 8123 --host homeassistant

# 3. Start Beacon
beacon start

Your Home Assistant is now accessible from the BeaconInfra dashboard — on your phone, from a hotel, wherever. The tunnel connects outbound from your device (no inbound ports needed), reconnects automatically, and works behind CGNAT.

The same tunnel works for Grafana, Jellyfin, Pi-hole, Nextcloud, your NAS admin page, a staging server — anything that speaks HTTP on your LAN.

Home Assistant setup: HA blocks proxied requests by default. Add this to your configuration.yaml (the file inside your HA config volume):

http:
  use_x_forwarded_for: true
  trusted_proxies:
    - 172.30.0.0/16
    - 172.16.0.0/12
    - 127.0.0.1

Then restart Home Assistant Core. Without this, the tunnel connects but HA can return 400 Bad Request or show "can't connect to Home Assistant" because it rejects the forwarded proxy headers.

---

🔑 Securing remote access

Remote terminal and tunnel sessions are reached through the BeaconInfra relay. By default the relay is gated by short-lived, authenticated tokens. If you want a second factor that the cloud cannot forge or replay, turn on the remote-access gate. Once configured, no remote terminal or tunnel session can open until you unlock it, and the unlock is verified on the device — the cloud only relays.

A passkey (WebAuthn) is the preferred factor; a passphrase is the fallback. On top of either, you can add an authenticator-app code (TOTP) as an out-of-band confirmation. Enroll whichever you like.

# Preferred: enroll a passkey (Touch ID / Windows Hello / security key / phone).
# Prints a one-time enrollment code to paste into the dashboard.
beacon remote-access add-passkey
beacon remote-access list-passkeys
beacon remote-access remove-passkey <id-or-label>

# Fallback: set (or change) a passphrase — prompted twice, no echo
beacon remote-access set-passphrase

# Optional out-of-band factor: scan the QR into an authenticator app.
# Every unlock then also asks for the current 6-digit code.
beacon remote-access setup-oob
beacon remote-access remove-oob

# Check what's configured
beacon remote-access status

# Remove everything (local recovery; disables the gate)
beacon remote-access clear

Restart beacon after changing factors so a running agent picks up the gate.

Why a passkey, not just a passphrase

In both factors, your passphrase never travels over the network. The browser keeps it local, derives a key from it, and sends only a one-time computed proof — the agent verifies that proof on the device. The cloud never sees the passphrase or anything reusable.

A passkey is simply safer still: there's no typed secret at all. Its private key lives in your authenticator hardware (Touch ID, Windows Hello, a security key, your phone) and is used to sign a one-time challenge; the agent stores only the public key and verifies the signature. Nothing the browser handles could be captured and replayed later, which is why passkeys are the preferred factor.

How enrollment works

1. Run beacon remote-access add-passkey on the device. It prints a one-time enrollment code (also visible in the Home Assistant add-on log), valid for a few minutes and usable once.
2. In the dashboard, choose Add passkey, enter the code, and complete your browser's passkey prompt (biometric / PIN).
3. The browser creates the passkey bound to the dashboard's domain (rpId) and sends the public key to the device. The agent verifies the registration and stores only the public key, credential id, rpId/origin, and a signature counter in ~/.beacon/remote-access.json (mode 0600).

Rooting enrollment in a device-local code (or a valid passphrase unlock) means a compromised cloud cannot enroll its own passkey — it never has the code.

To add the optional authenticator-app factor, run beacon remote-access setup-oob. It generates a TOTP secret and prints an otpauth:// QR code (and the plain secret) right in the terminal — or the Home Assistant add-on log. Scan it with any authenticator app (Google Authenticator, 1Password, Authy). The secret is created on the device and stored locally; it never reaches the cloud.

How an unlock works

Opening a terminal or tunnel is verified on the device:

1. A WebAuthn assertion. The agent issues a single-use, short-lived nonce as the challenge. Your authenticator signs it (user verification — biometric or PIN — is required). The agent verifies the signature against the stored public key, checks the rpId/origin it pinned at enrollment, the nonce, the user-present/user-verified flags, and a monotonic signature counter (replay defense). With the passphrase fallback, the browser instead returns a proof = HMAC-SHA256(Argon2id-key, nonce ‖ action ‖ session_id), compared in constant time. Either way the cloud sees no reusable secret.
2. The authenticator-app code, when enrolled. If you ran setup-oob, the unlock also asks for the current 6-digit TOTP code from your app. The agent verifies it against the locally-stored secret; the code is single-use within its window. This is generated on your phone and checked on the device — the cloud is never in the loop.

A successful unlock is in-memory, single-use, session-bound, and TTL-limited, and is cleared on restart (fail-closed). Repeated wrong attempts (assertion or code) trigger rate-limiting / backoff. Tunnels do not auto-start while the gate is configured — each comes up only on an unlocked connect, so a restart (which clears grants) requires unlocking again before any local service is reachable.

Why it's strong

• No reusable secret crosses the network. Only a one-time computed proof (or a passkey signature) is sent, and the device verifies it — there's nothing to capture and replay later.
• The cloud cannot silently open a session. Unlocking always takes a deliberate action on your own hardware — a biometric touch on your authenticator, and (when enrolled) the current code from your authenticator app, which the cloud never sees.

With no factor configured, behavior is unchanged (the gate is off, and tunnels auto-start as before).

---

⚡ Quick Start

1. Install

curl -fsSL https://raw.githubusercontent.com/Bajusz15/beacon/main/scripts/install.sh | bash

One static binary, no runtime dependencies. Builds for Linux (AMD64, ARM64, ARMv7) and macOS.

2. Initialize

beacon init --name my-pi

Writes ~/.beacon/config.yaml with your device name. No network calls, no account needed.

3. Start

beacon start

Dashboard at http://localhost:9100. System metrics, project health, Prometheus endpoint — all running locally.

4. (Optional) Connect to BeaconInfra

beacon cloud login --api-key usr_xxxxxxxx
beacon start   # restart to enable heartbeats + tunnels

The first heartbeat registers your device automatically. To disconnect: beacon cloud logout. Beacon makes zero outbound calls without an API key.

---

🛠️ Set up a project

Beacon manages your apps end-to-end: clone from Git or pull from Docker, run your deploy command, poll for updates, health check, and tail logs. Each project runs as its own isolated process — one crash doesn't affect others.

Interactive

beacon bootstrap myapp

The wizard asks for deployment type (Git or Docker), repo URL, tokens, and deploy command. It creates a systemd service and kicks off the first deployment.

From a config file

beacon bootstrap myapp -f bootstrap.yml

Git:

deployment_type: "git"
repo_url: "https://github.com/you/myapp.git"
git_token: "ghp_xxxxxxxxxxxx"
local_path: "$HOME/beacon/myapp"
deploy_command: "./scripts/deploy.sh"
poll_interval: "60s"

Docker:

deployment_type: "docker"
local_path: "$HOME/beacon/myapp"
poll_interval: "60s"
docker_images:
  - image: "ghcr.io/you/web-app"
    token: "ghp_xxxxxxxxxxxx"
    deploy_command: "docker compose up -d"
    docker_compose_files:
      - "docker-compose.yml"

Beacon talks to the registry API, detects the newest tag, pulls it, and runs your command. Supports Docker Hub, GHCR, and any Registry v2-compatible registry. Multiple images in one project are tracked independently — only the changed image redeploys.

Project secrets

Beacon can store encrypted deploy-time secrets per project and environment:

beacon secrets set API_TOKEN --project myapp --env prod
beacon secrets list --project myapp --env prod
beacon secrets list --reveal --project myapp --env prod
beacon secrets export --reveal --project myapp --env prod

Secrets live under ~/.beacon/secrets/<project>/<env>.enc and are encrypted with a local AES-256-GCM machine key at ~/.beacon/secrets/key. The key is created automatically with 0600 permissions.

During deploys, Beacon starts from the process environment, loads the existing BEACON_SECURE_ENV_PATH .env file when configured, then overlays Beacon secrets. That means Beacon secrets override matching .env values. Set BEACON_PROJECT_ENV=prod in the project env file to select an environment; if it is not set, Beacon uses default.

Values are not printed unless you pass --reveal. Use list for key names only, list --reveal to inspect all values, and export --reveal --format env|json for scripts.

Security note: the machine key is stored locally next to the encrypted secret files. This protects against accidental commits, backup leakage, and casual inspection; it is not meant to protect against someone who can already read your Beacon home directory.

Health checks

# ~/.beacon/config/projects/myapp/monitor.yml
checks:
  - name: "http_200"
    type: http
    url: "http://localhost:8080/health"
    interval: 30s

  - name: "process_running"
    type: process
    name: "myapp"

Alerts

# ~/.beacon/config/projects/myapp/alerts.yml
channels:
  - name: slack
    type: webhook
    url: "$WEBHOOK_URL"

routing:
  - severity: critical
    channels: [slack]
  - severity: warning
    channels: [slack]
    quiet_hours:
      start: "23:00"
      end: "07:00"
      timezone: "Europe/Budapest"

Test it: beacon alerts test --project myapp --severity critical

---

🖥️ Remote terminal

Open a shell on your device from the BeaconInfra dashboard — no SSH, no VPN, no open ports.

The agent picks up a terminal_open command via heartbeat, dials back to the cloud over WebSocket, and spawns a local PTY shell. Browser ↔ Cloud ↔ Agent, end-to-end. Sessions auto-expire after 15 minutes or 5 minutes idle.

Security: one-time tokens per session (SHA-256 hashed, server stores only the hash), shell restricted to a known allow-list (bash, zsh, sh, fish, etc.), runs as the Beacon agent's OS user.

---

🔒 WireGuard VPN

Turn any Beacon device into a peer-to-peer WireGuard exit node. Your traffic flows directly between devices — BeaconInfra only coordinates the key exchange and endpoint discovery.

# Home device (exit node — needs one port-forwarded UDP port)
beacon vpn enable --listen-port 51820

# Laptop (anywhere)
beacon vpn use my-home-pi

Use case: you're on airport WiFi and want to route through your home connection. No subscription, no third-party relay, no trust required. WireGuard is cryptographically silent — port scanners can't even tell it's listening.

Tear down: beacon vpn disable.

---

📖 What you can do with Beacon

Beacon does a lot in one binary. The tables below are a quick tour — if something looks useful, the sections above cover the full setup.

On your own machine (no account needed)

Everything here works without an internet connection and without signing up for anything.

You want to…	How
Deploy a Git repo automatically when you push a new tag	beacon bootstrap myapp — point it at your repo, give it your deploy script. Beacon polls for new tags and runs the script.
Deploy Docker images automatically from Docker Hub, GHCR, or any private registry	Use deployment_type: docker in your bootstrap config. Beacon watches for new tags and runs your docker compose up -d (or anything else).
Deploy a whole stack where each image moves independently	List multiple images under docker_images: in your bootstrap. Only the image that changed redeploys.
Check that an HTTP endpoint is up	Add an HTTP check to your project's monitor.yml — set a URL, an interval, and a timeout.
Check that a port is open (databases, SSH, custom services)	Add a type: port check with a host and port.
Check anything a shell command can check	Add a type: command check. The exit code tells Beacon if it's up.
See everything at a glance from the terminal	beacon status — colored summary of every project. Add --watch for a live view.
See everything in a browser	Open http://<your-device>:9100. Self-contained dashboard that auto-refreshes.
Pull metrics into Grafana / Prometheus	Scrape http://<your-device>:9100/metrics.
See CPU, memory, disk, load, temperature	Enabled by default. Shows up in beacon status and the dashboard.
Get a Slack / Discord / webhook message when something goes down	Create alerts.yml next to your monitor.yml. Route by severity to any webhook.
Get an email when something goes down	Same alerts.yml, add an email channel with your SMTP details.
Silence alerts at night	Add quiet_hours: to your alert routing with a start/end time and timezone.
Test your alert setup without waiting for an outage	beacon alerts test --project myapp --severity critical
Forward logs from a file, a Docker container, or journalctl	Add a log_sources: block to your monitor.yml. Filter with include/exclude patterns so you only ship what you care about.
Keep your tokens out of config files	beacon keys add — encrypted local token store for Git, Docker, webhooks.
Keep deploy secrets out of .env files	beacon secrets set API_TOKEN --project myapp --env prod. Beacon injects them after .env values during deploy.
Access Home Assistant, Grafana, or any local service remotely (with a BeaconInfra account — authenticated, no port-forwarding needed)	beacon tunnel add homeassistant --port 8123
Run several tunnels at once	beacon tunnel list / beacon tunnel enable / beacon tunnel disable
Route traffic through your home network from your laptop	beacon vpn enable on the exit node, beacon vpn use <device> on the client. Peer-to-peer WireGuard.
Query Beacon from Cursor or Claude Desktop	beacon mcp serve — see docs/MCP.md
Monitor a Kubernetes cluster	beacon source add with your kubeconfig.
Manage your project list	beacon projects list, beacon projects add, beacon projects status myapp

With a BeaconInfra account (optional)

A free BeaconInfra account adds a hosted dashboard and remote access on top of everything above. Your device keeps running locally — the cloud just gives you somewhere to see it all from a browser, including from your phone.

Turn it on with beacon cloud login --api-key usr_…. Turn it off any time with beacon cloud logout.

You want to…	What you get
See all your devices in one place	One dashboard showing every machine running Beacon — your Pi, your NAS, your VPS, your homelab server — with current health, uptime, and system metrics.
Open Home Assistant from your phone, anywhere	Set up the homeassistant tunnel once. From then on, open the BeaconInfra dashboard on your phone and click through to your HA UI. No VPN, no port-forwarding, no dynamic DNS.
Reach any other local service remotely	The same tunnel mechanism works for Grafana, Jellyfin, Pi-hole, your router's admin page, a staging VM — anything that speaks HTTP on your LAN.
View logs from anywhere	The log lines you configured to forward show up in the dashboard, filterable by device and project. Useful when something breaks and you don't want to SSH in.
Watch your metrics remotely	CPU, memory, disk, load, and temperature for every device — without being on the LAN.
See all your project health in one list	Every project, every check, across every device. Sorted so the problems come first.
Trigger a deploy from the browser	Click "deploy" in the dashboard and Beacon runs your existing deploy script on the device. Your secrets never leave home — the cloud just sends the signal.
Know when a device goes offline	If a device stops sending heartbeats, you get notified — even if its last check said everything was fine.
Open a remote terminal session	Click "Open terminal" on a device in the dashboard. The cloud relays a shell session (PTY) between your browser and the Beacon agent — no SSH port, no VPN needed. Sessions auto-expire after 15 minutes. Enroll a remote-access passkey or passphrase to require a device-verified second factor before any session opens.
Route traffic through your home network	beacon vpn enable on your home device + beacon vpn use my-pi on your laptop. WireGuard peer exchange happens via BeaconInfra; the actual traffic is peer-to-peer. For client-only machines, use the lightweight beacon-vpn binary.

🔐 What we don't see

Even with BeaconInfra enabled, some things stay on your device and never touch the cloud:

• Your source code and deploy scripts — the cloud only sends a "deploy now" signal; your device runs the script.
• Your tokens (Git, Docker, webhooks) — encrypted locally by beacon keys.
• Your application secrets (database passwords, API keys loaded via BEACON_SECURE_ENV_PATH or beacon secrets) — Beacon hands them to your app at deploy time and nothing else.
• Raw log files — only the lines you explicitly configured as log_sources are forwarded. Everything else stays on disk.
• The local dashboard at port 9100 — it keeps working offline, BeaconInfra account or not.

If you change your mind, beacon cloud logout stops all outbound reporting on the next heartbeat. There's nothing to delete from a control panel because there's no persistent account state beyond what you chose to send.

---

🏗️ Architecture

beacon start runs one orchestrator process per device (the "master"). It collects system metrics, serves the local dashboard, sends heartbeats, and supervises everything else. It's stateless per project — it doesn't know about Docker or systemd.

┌──────────────────────────────────────────────────────┐
│             BeaconInfra Cloud (optional)              │
│  heartbeats, commands, tunnel proxy, terminal relay   │
└──────────┬───────────────────────────┬───────────────┘
           │ HTTPS                     │ WebSocket
┌──────────┴───────────────────────────┴───────────────┐
│                  beacon start                        │
│                                                       │
│  One per device. System metrics, local dashboard,     │
│  heartbeats, project supervision, tunnel + VPN mgmt.  │
└──┬──────────────┬──────────────┬──────────┬──────────┘
   │ IPC          │ IPC          │ goroutine │ WireGuard
┌──┴───────────┐ ┌┴────────────┐ ┌┴─────────┐ ┌┴─────────┐
│ project agent│ │project agent│ │ tunnels   │ │ VPN      │
│ myapp        │ │ blog        │ │ HA  :8123 │ │ beacon0  │
│ health checks│ │ health check│ │ NC  :8080 │ │ 51820/UDP│
│ log tailing  │ │ log tailing │ │ (WS proxy)│ │          │
└──────────────┘ └─────────────┘ └───────────┘ └──────────┘

Projects are isolated: one crash doesn't affect others. The master auto-restarts failed projects with exponential backoff. Tunnels run as lightweight goroutines inside the master, connecting outbound to the cloud via WebSocket so local services are accessible without opening ports.

---

⌨️ Commands

Command	Purpose
beacon start	Start Beacon (dashboard, projects, tunnels, heartbeats)
beacon status	Terminal health view (--json, --watch, --no-color)
beacon init	Write local config (--name, --metrics-port; no network)
beacon cloud login / logout	Enable/disable cloud
beacon bootstrap <name>	Set up a project (interactive or -f config.yml)
beacon deploy	Git/Docker tag polling loop
beacon secrets set|get|list|export|remove	Local encrypted deploy secrets
beacon tunnel add|list|enable|disable	Reverse tunnels for remote access
beacon remote-access add-passkey|list-passkeys|remove-passkey	Enroll/manage passkeys (preferred) that gate remote terminal/tunnel sessions
beacon remote-access setup-oob|remove-oob	Enroll/remove an authenticator-app (TOTP) out-of-band factor
beacon remote-access set-passphrase|clear-passphrase|status|clear	Device-verified passphrase (fallback), gate status, and reset
beacon vpn enable|use|disable|status	WireGuard VPN
beacon projects list|add|remove|status	Project management
beacon alerts init|test|status	Alert routing
beacon keys list|add|rotate|delete	Encrypted token store
beacon mcp serve	MCP server for Cursor / Claude Desktop
beacon config show	Show resolved paths and identity
beacon update	Self-update to latest release

---

🔧 Run as a service

beacon bootstrap installs systemd services automatically. For manual setup:

cat > ~/.config/systemd/user/beacon.service << 'EOF'
[Unit]
Description=Beacon Agent
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
ExecStart=/usr/local/bin/beacon start
Restart=on-failure
RestartSec=30

[Install]
WantedBy=default.target
EOF

systemctl --user daemon-reload
systemctl --user enable --now beacon.service

---

📚 Documentation

• docs/MASTER_AGENT.md — agent architecture and heartbeats
• docs/VPN.md — WireGuard VPN setup and security model
• docs/LOG_FORWARDING.md — log forwarding
• docs/KEY_MANAGEMENT.md — encrypted key store
• docs/MCP.md — MCP server for editors
• examples/ — bootstrap, monitor, alert configs

---

☕ Buy me a coffee — if Beacon saves you time.

License

Apache 2.0 — see LICENSE