{"id":36534518,"url":"https://github.com/bajusz15/beacon","last_synced_at":"2026-05-30T20:00:56.564Z","repository":{"id":303558529,"uuid":"1015860361","full_name":"Bajusz15/beacon","owner":"Bajusz15","description":"Lightweight open-source deployment and monitoring agent for self-hosted or home-lab servers and devices such as Raspberry Pi, N100, or any Linux server. Future proof your deployments with automation and monitoring.","archived":false,"fork":false,"pushed_at":"2026-05-24T20:36:21.000Z","size":27967,"stargazers_count":11,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-24T21:22:12.699Z","etag":null,"topics":["home-lab","home-lab-dashboard","home-security","hosting-deployment","iot","iot-application","monitoring","monitoring-automation","self-hosted"],"latest_commit_sha":null,"homepage":"https://beaconinfra.dev","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Bajusz15.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-07-08T06:32:03.000Z","updated_at":"2026-05-24T20:27:31.000Z","dependencies_parsed_at":"2025-09-23T22:08:41.544Z","dependency_job_id":"e89d779f-9a8a-4bbf-b69d-8256b86ae8c0","html_url":"https://github.com/Bajusz15/beacon","commit_stats":null,"previous_names":["bajusz15/beacon"],"tags_count":19,"template":false,"template_full_name":null,"purl":"pkg:github/Bajusz15/beacon","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Bajusz15%2Fbeacon","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Bajusz15%2Fbeacon/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Bajusz15%2Fbeacon/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Bajusz15%2Fbeacon/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Bajusz15","download_url":"https://codeload.github.com/Bajusz15/beacon/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Bajusz15%2Fbeacon/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33452033,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-24T19:21:36.376Z","status":"ssl_error","status_checked_at":"2026-05-24T19:21:10.562Z","response_time":57,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["home-lab","home-lab-dashboard","home-security","hosting-deployment","iot","iot-application","monitoring","monitoring-automation","self-hosted"],"created_at":"2026-01-12T03:06:52.421Z","updated_at":"2026-05-30T20:00:56.556Z","avatar_url":"https://github.com/Bajusz15.png","language":"Go","funding_links":["https://buymeacoffee.com/matebajusz"],"categories":[],"sub_categories":[],"readme":"# Beacon\n\n\u003cimg src=\"./docs/logo.png\" alt=\"Beacon Logo\" width=\"120\" height=\"120\"\u003e\n\n**Securely reach and monitor every machine you run — from one binary. No open ports, and nothing sensitive ever leaves your box.**\n\n[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n[![Go Version](https://img.shields.io/badge/Go-1.24+-00ADD8?style=flat\u0026logo=go)](https://golang.org/)\n[![Platform](https://img.shields.io/badge/Platform-Linux%20%7C%20macOS-lightgrey)](https://github.com/Bajusz15/beacon/releases)\n[![CI](https://github.com/Bajusz15/beacon/workflows/CI/badge.svg)](https://github.com/Bajusz15/beacon/actions)\n[![Go Report Card](https://goreportcard.com/badge/github.com/Bajusz15/beacon)](https://goreportcard.com/report/github.com/Bajusz15/beacon)\n\n---\n\nYou 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.)\n\nAnd 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.\n\n```\n⬡ beacon v0.3.2  ● running  pid 1847  uptime 14d 3h\n\nDEVICE  pi-homelab  192.168.1.42  arm64  Debian 12\n\nSYSTEM  cpu 12% ████░░░░░░░░░░░░  mem 67% ██████████░░░░░░  disk 41% ██████░░░░░░░░░░\n        load 0.42 0.38 0.35  temp 48°C\n\nPROJECTS  3 healthy  1 warning  0 down\n\n  ● portfolio-site      v2.1.0   deployed 2h ago    3/3 checks passing\n  ● home-assistant      v2024.3  deployed 5d ago    2/2 checks passing\n  ◐ nextcloud           v28.0.1  deployed 3d ago    2/3 checks passing\n    └─ ⚠ HTTP https://cloud.local/status  timeout 5.2s \u003e 3s threshold\n```\n\nThat's `beacon status`. There's also a browser dashboard at `http://localhost:9100` — self-contained, no CDN, works offline.\n\n---\n\n## ✨ What Beacon does\n\nTwo things first — **secure remote access** and **monitoring** — on a zero-trust foundation. Everything else is a bonus.\n\n### 🔐 Built zero-trust, local-first\n\nThis is the part that matters before any feature:\n\n- **No open ports.** Tunnels connect *outbound* from your device — nothing is exposed to the internet, and it works behind CGNAT.\n- **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.\n- **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.\n- **Works offline.** The agent and its dashboard run fully local, with no account.\n\n### 🌐 Remote access\n\n- **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.\n- **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.\n- **Passphrase-gated (recommended)** — set a device-local passphrase 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 challenge and never sees the passphrase or a reusable proof, so even a fully compromised cloud can't open a session without it. See [Securing remote access](#-securing-remote-access).\n\n### 📊 Monitoring \u0026 alerts\n\n- **Health \u0026 metrics** — health checks (HTTP, port, command), CPU/memory/disk/temperature, per-project status, Prometheus metrics.\n- **Alerts** — via webhook (Slack, Discord) or SMTP, with quiet hours and offline-device detection.\n- **Log forwarding** — tail log files, Docker container logs, or `journalctl` and forward them to the dashboard, filtered so you only ship what matters.\n\n### 🧰 Also\n\n- **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.\n- **WireGuard VPN** — turn any Beacon device into a peer-to-peer WireGuard exit node and route traffic through your home network from a laptop.\n\n[BeaconInfra](https://beaconinfra.dev) 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.\n\n---\n\n## 🧩 One layer across every machine\n\nBeacon isn't a PaaS and doesn't replace how you deploy. It's the operations layer **across all your\nmachines** — the box running your apps *and* the Home Assistant box, the NAS, the Pis, the client\nserver, the VPS you never containerized — so you reach, watch, and fix every one of them from a\nsingle place, without handing any cloud root over your hardware.\n\n---\n\n## 🏠 Access Home Assistant from anywhere\n\nIf you run Home Assistant OS, the primary path is the Beacon Home Assistant add-on:\ninstall the add-on, paste your BeaconInfra API key, enable `tunnel_home_assistant`,\nand start it. The add-on points the tunnel at Home Assistant Core on\n`http://homeassistant:8123`.\n\nIf you run Beacon on a normal Linux host or in Docker next to Home Assistant, use\nthe CLI tunnel flow. Three commands, no port-forwarding, no Nabu Casa.\n\n```bash\n# 1. Log in to BeaconInfra (free account)\nbeacon cloud login --api-key usr_xxxxxxxx\n\n# 2. Expose Home Assistant\nbeacon tunnel add homeassistant --port 8123\n# Or, for Docker Compose / HA OS style service DNS:\n# beacon tunnel add homeassistant --port 8123 --host homeassistant\n\n# 3. Start Beacon\nbeacon start\n```\n\nYour 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.\n\nThe same tunnel works for Grafana, Jellyfin, Pi-hole, Nextcloud, your NAS admin page, a staging server — anything that speaks HTTP on your LAN.\n\n**Home Assistant setup:** HA blocks proxied requests by default. Add this to your `configuration.yaml` (the file inside your HA config volume):\n\n```yaml\nhttp:\n  use_x_forwarded_for: true\n  trusted_proxies:\n    - 172.30.0.0/16\n    - 172.16.0.0/12\n    - 127.0.0.1\n```\n\nThen 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.\n\n---\n\n## 🔑 Securing remote access\n\nRemote terminal and tunnel sessions are reached through the BeaconInfra relay. By\ndefault the relay is gated by short-lived, authenticated tokens — but if you want\na second factor that does **not** trust the cloud at all, set a remote-access\npassphrase. Once set, no remote terminal or tunnel session can open until the\npassphrase is supplied and verified locally on the device.\n\n```bash\n# Set (or change) the passphrase — prompted twice, no echo\nbeacon remote-access set-passphrase\n\n# Check whether the gate is on\nbeacon remote-access status\n\n# Remove it (local recovery; disables the gate)\nbeacon remote-access clear\n```\n\nRestart `beacon` after setting it so a running agent picks up the gate.\n\n**How it stays secure — the cloud never sees your passphrase:**\n\n- The passphrase is **never stored**. Setup writes only an Argon2id-derived key,\n  its salt, and the cost parameters to `~/.beacon/remote-access.json` (mode `0600`).\n- At session time the agent issues a single-use, short-lived **nonce**. The browser\n  derives the key from your passphrase and returns a proof =\n  `HMAC-SHA256(key, nonce ‖ action ‖ session_id)`. The agent recomputes and compares\n  it in constant time. BeaconInfra only relays this challenge — it never sees the\n  passphrase or any reusable proof, so a **fully compromised cloud still cannot open\n  a session**.\n- A successful unlock is **in-memory, session-bound, and TTL-limited**, and is\n  cleared on restart (fail-closed).\n- Repeated wrong attempts trigger **rate-limiting / backoff** to slow brute force.\n\nWith no passphrase set, behavior is unchanged (the gate is simply off).\n\n---\n\n## ⚡ Quick Start\n\n### 1. Install\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/Bajusz15/beacon/main/scripts/install.sh | bash\n```\n\nOne static binary, no runtime dependencies. Builds for Linux (AMD64, ARM64, ARMv7) and macOS.\n\n### 2. Initialize\n\n```bash\nbeacon init --name my-pi\n```\n\nWrites `~/.beacon/config.yaml` with your device name. No network calls, no account needed.\n\n### 3. Start\n\n```bash\nbeacon start\n```\n\nDashboard at `http://localhost:9100`. System metrics, project health, Prometheus endpoint — all running locally.\n\n### 4. (Optional) Connect to BeaconInfra\n\n```bash\nbeacon cloud login --api-key usr_xxxxxxxx\nbeacon start   # restart to enable heartbeats + tunnels\n```\n\nThe first heartbeat registers your device automatically. To disconnect: `beacon cloud logout`. Beacon makes zero outbound calls without an API key.\n\n---\n\n## 🛠️ Set up a project\n\nBeacon 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.\n\n### Interactive\n\n```bash\nbeacon bootstrap myapp\n```\n\nThe 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.\n\n### From a config file\n\n```bash\nbeacon bootstrap myapp -f bootstrap.yml\n```\n\n**Git:**\n\n```yaml\ndeployment_type: \"git\"\nrepo_url: \"https://github.com/you/myapp.git\"\ngit_token: \"ghp_xxxxxxxxxxxx\"\nlocal_path: \"$HOME/beacon/myapp\"\ndeploy_command: \"./scripts/deploy.sh\"\npoll_interval: \"60s\"\n```\n\n**Docker:**\n\n```yaml\ndeployment_type: \"docker\"\nlocal_path: \"$HOME/beacon/myapp\"\npoll_interval: \"60s\"\ndocker_images:\n  - image: \"ghcr.io/you/web-app\"\n    token: \"ghp_xxxxxxxxxxxx\"\n    deploy_command: \"docker compose up -d\"\n    docker_compose_files:\n      - \"docker-compose.yml\"\n```\n\nBeacon 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.\n\n### Project secrets\n\nBeacon can store encrypted deploy-time secrets per project and environment:\n\n```bash\nbeacon secrets set API_TOKEN --project myapp --env prod\nbeacon secrets list --project myapp --env prod\nbeacon secrets list --reveal --project myapp --env prod\nbeacon secrets export --reveal --project myapp --env prod\n```\n\nSecrets live under `~/.beacon/secrets/\u003cproject\u003e/\u003cenv\u003e.enc` and are encrypted with a local AES-256-GCM machine key at `~/.beacon/secrets/key`. The key is created automatically with `0600` permissions.\n\nDuring 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`.\n\nValues 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.\n\nSecurity 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.\n\n### Health checks\n\n```yaml\n# ~/.beacon/config/projects/myapp/monitor.yml\nchecks:\n  - name: \"http_200\"\n    type: http\n    url: \"http://localhost:8080/health\"\n    interval: 30s\n\n  - name: \"process_running\"\n    type: process\n    name: \"myapp\"\n```\n\n### Alerts\n\n```yaml\n# ~/.beacon/config/projects/myapp/alerts.yml\nchannels:\n  - name: slack\n    type: webhook\n    url: \"$WEBHOOK_URL\"\n\nrouting:\n  - severity: critical\n    channels: [slack]\n  - severity: warning\n    channels: [slack]\n    quiet_hours:\n      start: \"23:00\"\n      end: \"07:00\"\n      timezone: \"Europe/Budapest\"\n```\n\nTest it: `beacon alerts test --project myapp --severity critical`\n\n---\n\n## 🖥️ Remote terminal\n\nOpen a shell on your device from the BeaconInfra dashboard — no SSH, no VPN, no open ports.\n\nThe 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.\n\nSecurity: 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.\n\n---\n\n## 🔒 WireGuard VPN\n\nTurn 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.\n\n```bash\n# Home device (exit node — needs one port-forwarded UDP port)\nbeacon vpn enable --listen-port 51820\n\n# Laptop (anywhere)\nbeacon vpn use my-home-pi\n```\n\nUse 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.\n\nTear down: `beacon vpn disable`.\n\n---\n\n## 📖 What you can do with Beacon\n\nBeacon does a lot in one binary. The tables below are a quick tour — if something looks useful, the sections above cover the full setup.\n\n### On your own machine (no account needed)\n\nEverything here works without an internet connection and without signing up for anything.\n\n| You want to… | How |\n|---|---|\n| **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. |\n| **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). |\n| **Deploy a whole stack** where each image moves independently | List multiple images under `docker_images:` in your bootstrap. Only the image that changed redeploys. |\n| **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. |\n| **Check that a port is open** (databases, SSH, custom services) | Add a `type: port` check with a host and port. |\n| **Check anything a shell command can check** | Add a `type: command` check. The exit code tells Beacon if it's up. |\n| **See everything at a glance from the terminal** | `beacon status` — colored summary of every project. Add `--watch` for a live view. |\n| **See everything in a browser** | Open `http://\u003cyour-device\u003e:9100`. Self-contained dashboard that auto-refreshes. |\n| **Pull metrics into Grafana / Prometheus** | Scrape `http://\u003cyour-device\u003e:9100/metrics`. |\n| **See CPU, memory, disk, load, temperature** | Enabled by default. Shows up in `beacon status` and the dashboard. |\n| **Get a Slack / Discord / webhook message when something goes down** | Create `alerts.yml` next to your `monitor.yml`. Route by severity to any webhook. |\n| **Get an email when something goes down** | Same `alerts.yml`, add an `email` channel with your SMTP details. |\n| **Silence alerts at night** | Add `quiet_hours:` to your alert routing with a start/end time and timezone. |\n| **Test your alert setup without waiting for an outage** | `beacon alerts test --project myapp --severity critical` |\n| **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. |\n| **Keep your tokens out of config files** | `beacon keys add` — encrypted local token store for Git, Docker, webhooks. |\n| **Keep deploy secrets out of `.env` files** | `beacon secrets set API_TOKEN --project myapp --env prod`. Beacon injects them after `.env` values during deploy. |\n| **Access Home Assistant, Grafana, or any local service remotely** (with a BeaconInfra account — authenticated, no port-forwarding needed) | `beacon tunnel add homeassistant --port 8123` |\n| **Run several tunnels at once** | `beacon tunnel list` / `beacon tunnel enable` / `beacon tunnel disable` |\n| **Route traffic through your home network from your laptop** | `beacon vpn enable` on the exit node, `beacon vpn use \u003cdevice\u003e` on the client. Peer-to-peer WireGuard. |\n| **Query Beacon from Cursor or Claude Desktop** | `beacon mcp serve` — see [docs/MCP.md](./docs/MCP.md) |\n| **Monitor a Kubernetes cluster** | `beacon source add` with your kubeconfig. |\n| **Manage your project list** | `beacon projects list`, `beacon projects add`, `beacon projects status myapp` |\n\n### With a BeaconInfra account (optional)\n\nA 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.\n\nTurn it on with `beacon cloud login --api-key usr_…`. Turn it off any time with `beacon cloud logout`.\n\n| You want to… | What you get |\n|---|---|\n| **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. |\n| **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. |\n| **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. |\n| **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. |\n| **Watch your metrics remotely** | CPU, memory, disk, load, and temperature for every device — without being on the LAN. |\n| **See all your project health in one list** | Every project, every check, across every device. Sorted so the problems come first. |\n| **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. |\n| **Know when a device goes offline** | If a device stops sending heartbeats, you get notified — even if its last check said everything was fine. |\n| **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. Set a [remote-access passphrase](#-securing-remote-access) to require a device-verified second factor before any session opens. |\n| **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. |\n\n### 🔐 What we don't see\n\nEven with BeaconInfra enabled, some things stay on your device and never touch the cloud:\n\n- Your **source code** and **deploy scripts** — the cloud only sends a \"deploy now\" signal; your device runs the script.\n- Your **tokens** (Git, Docker, webhooks) — encrypted locally by `beacon keys`.\n- 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.\n- **Raw log files** — only the lines you explicitly configured as `log_sources` are forwarded. Everything else stays on disk.\n- The **local dashboard** at port 9100 — it keeps working offline, BeaconInfra account or not.\n\nIf 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.\n\n---\n\n## 🏗️ Architecture\n\n`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.\n\n```\n┌──────────────────────────────────────────────────────┐\n│             BeaconInfra Cloud (optional)              │\n│  heartbeats, commands, tunnel proxy, terminal relay   │\n└──────────┬───────────────────────────┬───────────────┘\n           │ HTTPS                     │ WebSocket\n┌──────────┴───────────────────────────┴───────────────┐\n│                  beacon start                        │\n│                                                       │\n│  One per device. System metrics, local dashboard,     │\n│  heartbeats, project supervision, tunnel + VPN mgmt.  │\n└──┬──────────────┬──────────────┬──────────┬──────────┘\n   │ IPC          │ IPC          │ goroutine │ WireGuard\n┌──┴───────────┐ ┌┴────────────┐ ┌┴─────────┐ ┌┴─────────┐\n│ project agent│ │project agent│ │ tunnels   │ │ VPN      │\n│ myapp        │ │ blog        │ │ HA  :8123 │ │ beacon0  │\n│ health checks│ │ health check│ │ NC  :8080 │ │ 51820/UDP│\n│ log tailing  │ │ log tailing │ │ (WS proxy)│ │          │\n└──────────────┘ └─────────────┘ └───────────┘ └──────────┘\n```\n\nProjects 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.\n\n---\n\n## ⌨️ Commands\n\n| Command | Purpose |\n|---------|---------|\n| `beacon start` | Start Beacon (dashboard, projects, tunnels, heartbeats) |\n| `beacon status` | Terminal health view (`--json`, `--watch`, `--no-color`) |\n| `beacon init` | Write local config (`--name`, `--metrics-port`; no network) |\n| `beacon cloud login` / `logout` | Enable/disable cloud |\n| `beacon bootstrap \u003cname\u003e` | Set up a project (interactive or `-f config.yml`) |\n| `beacon deploy` | Git/Docker tag polling loop |\n| `beacon secrets set\\|get\\|list\\|export\\|remove` | Local encrypted deploy secrets |\n| `beacon tunnel add\\|list\\|enable\\|disable` | Reverse tunnels for remote access |\n| `beacon remote-access set-passphrase\\|status\\|clear` | Device-verified passphrase gating remote terminal/tunnel sessions |\n| `beacon vpn enable\\|use\\|disable\\|status` | WireGuard VPN |\n| `beacon projects list\\|add\\|remove\\|status` | Project management |\n| `beacon alerts init\\|test\\|status` | Alert routing |\n| `beacon keys list\\|add\\|rotate\\|delete` | Encrypted token store |\n| `beacon mcp serve` | MCP server for Cursor / Claude Desktop |\n| `beacon config show` | Show resolved paths and identity |\n| `beacon update` | Self-update to latest release |\n\n---\n\n## 🔧 Run as a service\n\n`beacon bootstrap` installs systemd services automatically. For manual setup:\n\n```bash\ncat \u003e ~/.config/systemd/user/beacon.service \u003c\u003c 'EOF'\n[Unit]\nDescription=Beacon Agent\nAfter=network-online.target\nWants=network-online.target\n\n[Service]\nType=simple\nExecStart=/usr/local/bin/beacon start\nRestart=on-failure\nRestartSec=30\n\n[Install]\nWantedBy=default.target\nEOF\n\nsystemctl --user daemon-reload\nsystemctl --user enable --now beacon.service\n```\n\n---\n\n## 📚 Documentation\n\n- [docs/MASTER_AGENT.md](./docs/MASTER_AGENT.md) — agent architecture and heartbeats\n- [docs/VPN.md](./docs/VPN.md) — WireGuard VPN setup and security model\n- [docs/LOG_FORWARDING.md](./docs/LOG_FORWARDING.md) — log forwarding\n- [docs/KEY_MANAGEMENT.md](./docs/KEY_MANAGEMENT.md) — encrypted key store\n- [docs/MCP.md](./docs/MCP.md) — MCP server for editors\n- [examples/](./examples/) — bootstrap, monitor, alert configs\n\n---\n\n☕ **[Buy me a coffee](https://buymeacoffee.com/matebajusz)** — if Beacon saves you time.\n\n## License\n\nApache 2.0 — see [LICENSE](./LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbajusz15%2Fbeacon","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbajusz15%2Fbeacon","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbajusz15%2Fbeacon/lists"}