{"id":48854042,"url":"https://github.com/manusa/ai-beacon","last_synced_at":"2026-07-02T09:01:18.573Z","repository":{"id":351510727,"uuid":"1211183428","full_name":"manusa/ai-beacon","owner":"manusa","description":"A web dashboard for monitoring and orchestrating AI coding agents across your devices.","archived":false,"fork":false,"pushed_at":"2026-06-02T08:25:25.000Z","size":41648,"stargazers_count":25,"open_issues_count":11,"forks_count":2,"subscribers_count":3,"default_branch":"main","last_synced_at":"2026-06-02T09:18:03.861Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://github.com/manusa/ai-beacon","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/manusa.png","metadata":{"files":{"readme":"README.md","changelog":null,"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":"2026-04-15T06:31:44.000Z","updated_at":"2026-06-02T07:26:31.000Z","dependencies_parsed_at":"2026-05-08T07:02:49.255Z","dependency_job_id":null,"html_url":"https://github.com/manusa/ai-beacon","commit_stats":null,"previous_names":["manusa/ai-beacon"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/manusa/ai-beacon","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/manusa%2Fai-beacon","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/manusa%2Fai-beacon/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/manusa%2Fai-beacon/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/manusa%2Fai-beacon/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/manusa","download_url":"https://codeload.github.com/manusa/ai-beacon/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/manusa%2Fai-beacon/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35040024,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-02T02:00:06.368Z","response_time":173,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":[],"created_at":"2026-04-15T11:02:22.844Z","updated_at":"2026-07-02T09:01:18.543Z","avatar_url":"https://github.com/manusa.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AI Beacon\n\n\u003cdiv align=\"center\"\u003e\n\n✨ [Features](#features) | 🚀 [Deploy](#deploy) | ⚙️ [Configuration](#agent-configuration) | 📖 [Docs](docs/README.md) | 💬 [Discussions](https://github.com/manusa/ai-beacon/discussions)\n\n\u003c/div\u003e\n\nWatch every coding agent on every machine — and step in the moment one needs you.\n\n![AI Beacon dashboard — live view of multiple Claude Code sessions across devices](docs/assets/demo.gif)\n\n\u003cdiv align=\"center\"\u003e\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd width=\"50%\" align=\"center\"\u003e\n\n### ☁️ Try in the cloud (~2 min, free)\n\nOpenShift Developer Sandbox, no credit card.\n\n**[→ Deploy to the Sandbox](#deploy-to-openshift-developer-sandbox)**\n\n\u003c/td\u003e\n\u003ctd width=\"50%\" align=\"center\"\u003e\n\n### 💻 Run locally (~30s, Docker)\n\nOne container, one port, one volume.\n\n**[→ Run with Docker](#run-locally-with-docker)**\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n\u003c/div\u003e\n\n\u003ca id=\"why-ai-beacon\"\u003e\u003c/a\u003e\n## 💡 Why AI Beacon\n\n- **Catch the moment an agent needs you.** Permission prompts, idle sessions, finished runs — paged to you instead of buried across terminals you forgot to check.\n- **One view of the whole fleet.** Every session, every machine — model, branch, context, PR — in a single glance.\n- **Unblock from anywhere.** Open the dashboard on your phone, attach to the session's terminal, type the answer, walk away.\n\n**Your data stays on your machines. Uninstall is one command.**\n\n*I run my fleet on this every day across 3 machines.* — Marc\n\n\u003ca id=\"features\"\u003e\u003c/a\u003e\n## ✨ Features\n\n1. **Browser terminal** — attach to any session from any device, including your phone.\n2. **Push notifications that survive a closed tab** — a service worker keeps you reachable after you've moved on.\n3. **Workflow templates** — *Implement Issue* and *Review PR* prime sessions with opinionated, scope-first prompts (TDD, root-cause, multi-persona review) instead of spawning blank shells.\n4. **Worktree-aware session spawning** from the browser — start a session on a fresh branch and a fresh worktree in one click.\n5. **Real-time multi-machine dashboard** — model, context, cost, branch, PR status per session.\n6. **Status detection** — *working* / *idle* / *awaiting permission*, surfaced as the session state.\n7. **Pluggable agents** — Claude Code and OpenCode today; plugin SDK in Go for the rest.\n8. **Multi-deploy** — native binary, Docker, Helm, OpenShift Sandbox, Hugging Face Spaces.\n9. **Auth modes** — PSK, password, OIDC, OAuth Proxy, Hugging Face identity.\n10. **Native Linux / macOS / Windows binaries** (amd64 + arm64).\n\n\u003e [!NOTE]\n\u003e **Early access** — binaries, container image, and Helm chart are available now; source will be published after this validation phase. Currently supports **Claude Code** and **OpenCode** (more agents planned via the plugin SDK). Feedback via [issues](https://github.com/manusa/ai-beacon/issues) and [discussions](https://github.com/manusa/ai-beacon/discussions) is the whole point of this phase — please open one.\n\u003e\n\u003e **Support:** Marc responds personally to [Discussions](https://github.com/manusa/ai-beacon/discussions) within 24 hours. Stuck on install? @-mention `@manusa` in the thread for a faster reply.\n\n\u003ca id=\"deploy\"\u003e\u003c/a\u003e\n## 🚀 Deploy\n\nPick a deployment method and follow the steps — the built-in setup guide will walk you through connecting your first agent.\n\n| Method | Best for |\n|--------|----------|\n| [OpenShift Developer Sandbox](#deploy-to-openshift-developer-sandbox) | Free cloud dashboard, no credit card |\n| [Docker (local)](#run-locally-with-docker) | The fastest way to try the dashboard on your own machine |\n| [Any Kubernetes cluster](#deploy-to-any-kubernetes-cluster) | Your own cluster with Helm |\n| [Hugging Face Spaces](#deploy-to-hugging-face-spaces) | Free cloud dashboard gated by your Hugging Face account |\n\nPower users can also grab a [native binary](docs/connect-agent.md#native-binaries) directly — Linux, macOS, or Windows.\n\n\u003ca id=\"deploy-to-openshift-developer-sandbox\"\u003e\u003c/a\u003e\n### Deploy to OpenShift Developer Sandbox\n\nThe [Developer Sandbox](https://developers.redhat.com/developer-sandbox) is free and available to anyone with a Red Hat account. The same recipe works on any OpenShift cluster.\n\n```bash\n# 1. Set the agent token\n#    The token authenticates agents to the dashboard. Browser login uses\n#    your OpenShift / Red Hat account via the OAuth Proxy sidecar — no\n#    password to manage. Only usernames listed in --set allowedUsers can\n#    sign in; the snippet below allows your current OpenShift user.\nexport TOKEN=$(openssl rand -hex 32)\n\n# 2. Install (into your current namespace — the sandbox assigns one for you)\nhelm install ai-beacon \\\n  oci://ghcr.io/manusa/charts/ai-beacon \\\n  --version 0.0.0-snapshot \\\n  --set openshift=true \\\n  --set oauthProxy.enabled=true \\\n  --set persistence.enabled=false \\\n  --set auth.token=\"$TOKEN\" \\\n  --set allowedUsers=\"{$(oc whoami)}\"\n\n# 3. Get the dashboard URL\noc get route ai-beacon -o jsonpath='https://{.spec.host}'\n```\n\nOpen the dashboard URL in your browser. You'll be redirected to OpenShift to log in with your Red Hat account, then asked to authorize the dashboard.\n\nOnce inside, click the **rocket icon** in the top bar to open the setup guide:\n\n\u003cdiv align=\"center\"\u003e\n  \u003cpicture\u003e\n    \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"docs/assets/app-bar-dark.png\"\u003e\n    \u003cimg alt=\"AI Beacon top bar — click the rocket icon on the right to open the setup guide\" src=\"docs/assets/app-bar-light.png\" width=\"720\"\u003e\n  \u003c/picture\u003e\n\u003c/div\u003e\n\nThe guide walks you through downloading the CLI and connecting your first agent. Then head to [Agent configuration](#agent-configuration) for optional tuning.\n\n\u003e [!NOTE]\n\u003e `--version 0.0.0-snapshot` is a rolling pre-release alias that tracks the latest build.\n\u003e It is required until a stable release is published.\n\n\u003ca id=\"run-locally-with-docker\"\u003e\u003c/a\u003e\n### Run locally with Docker\n\nThe fastest way to try the dashboard on your own machine. No cluster, no signup.\n\n\u003e Don't have Docker yet? Install it from [docs.docker.com/get-started](https://docs.docker.com/get-started/get-docker/). If you prefer Podman, replace `docker` with `podman` in every command below — the recipe is identical.\n\n```bash\ndocker volume create ai-beacon\ndocker run --pull=always \\\n  -e AI_BEACON_AUTH_PASSWORD=demo \\\n  -p 8080:8080 \\\n  -v ai-beacon:/data \\\n  ghcr.io/manusa/ai-beacon:latest\n```\n\nOpen \u003chttp://localhost:8080\u003e and log in with password **demo**.\n\nThe dashboard will be empty until you connect an agent — click the **rocket icon** in the top bar to open the setup guide:\n\n\u003cdiv align=\"center\"\u003e\n  \u003cpicture\u003e\n    \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"docs/assets/app-bar-dark.png\"\u003e\n    \u003cimg alt=\"AI Beacon top bar — click the rocket icon on the right to open the setup guide\" src=\"docs/assets/app-bar-light.png\" width=\"720\"\u003e\n  \u003c/picture\u003e\n\u003c/div\u003e\n\nThen head to [Agent configuration](#agent-configuration) for optional tuning.\n\n\u003e [!IMPORTANT]\n\u003e Mount `/data` to a persistent volume (named volume above, or a bind mount). The agent auth token lives there; without a volume, every container restart regenerates it and silently invalidates the token baked into your installed agent hooks — sessions stop appearing on the dashboard until you re-run `ai-beacon install` with the new token.\n\nTo inspect the auto-generated agent token from a running container:\n\n```bash\ndocker exec $(docker ps -qf ancestor=ghcr.io/manusa/ai-beacon) cat /data/token\n```\n\n\u003ca id=\"deploy-to-any-kubernetes-cluster\"\u003e\u003c/a\u003e\n### Deploy to any Kubernetes cluster\n\n```bash\nexport TOKEN=$(openssl rand -hex 32)\nexport PASSWORD=changeme\n\nhelm install ai-beacon \\\n  oci://ghcr.io/manusa/charts/ai-beacon \\\n  --version 0.0.0-snapshot \\\n  --set ingress.host=ai-beacon.example.com \\\n  --set auth.token=\"$TOKEN\" \\\n  --set auth.password=\"$PASSWORD\" \\\n  -n ai-beacon --create-namespace\n```\n\nOn clusters with persistent storage, you can omit `auth.token` and `auth.password` — credentials are auto-generated and persisted to the volume. Retrieve them with:\n\n```bash\nkubectl exec -n ai-beacon deploy/ai-beacon -- cat /data/password\nkubectl exec -n ai-beacon deploy/ai-beacon -- cat /data/token\n```\n\nSee [Agent configuration](#agent-configuration) for optional tuning.\n\n\u003ca id=\"deploy-to-hugging-face-spaces\"\u003e\u003c/a\u003e\n### Deploy to Hugging Face Spaces\n\nHugging Face's free CPU tier accepts arbitrary Docker images and projects the signed-in HF user's identity into the container via OAuth/OIDC — so the dashboard's \"who is allowed in\" question is answered by your existing Hugging Face account, with no IdP to configure and no password to manage.\n\nThe full recipe lives in [`huggingface-space/`](huggingface-space/README.md): push that directory to a fresh Space, set two secrets, restart the Space. The auth side is covered in [`docs/auth.md`](docs/auth.md#oidc-bring-your-own-idp).\n\n\u003ca id=\"recommended-tools\"\u003e\u003c/a\u003e\n## 🛠️ Recommended tools\n\nAI Beacon works out of the box, but most features require these tools on the machines running your agents:\n\n| Tool | What it unlocks |\n|------|----------------|\n| [`git`](https://git-scm.com/) | Current branch display, worktree management |\n| [`gh`](https://cli.github.com/) (authenticated) | PR status and checks on session cards, review and merge PRs from the dashboard |\n\nWithout them the dashboard still tracks every session's model, context usage, cost, and duration.\n\n\u003ca id=\"agent-configuration\"\u003e\u003c/a\u003e\n## ⚙️ Agent configuration\n\nThe setup guide covers installing the CLI and connecting to the server.\nThese additional environment variables are optional but useful:\n\n| Variable | Purpose | Default |\n|----------|---------|---------|\n| `AI_BEACON_PROJECTS_DIR` | Base directories for your repositories — enables spawning new sessions and worktree workflows from the dashboard. Accepts one path or a list joined by the OS path separator (`:` on Unix, `;` on Windows) | _(disabled)_ |\n| `AI_BEACON_DEVICE_NAME` | Friendly name shown in the dashboard for this machine | hostname |\n\nSet them in your shell profile (e.g. `~/.zshrc`) so they apply to every session:\n\n```bash\nexport AI_BEACON_PROJECTS_DIR=~/projects\nexport AI_BEACON_DEVICE_NAME=macbook\n```\n\nEvery other knob — server flags, Helm values, the `config.toml` file, data-directory layout — lives in [`docs/configuration.md`](docs/configuration.md).\n\n\u003ca id=\"documentation\"\u003e\u003c/a\u003e\n## 📖 Documentation\n\nFor everything beyond the initial deploy and first session — multi-machine setup, auth modes (OIDC, proxy-header), GitHub integration, workflow prompts, the full configuration surface, and troubleshooting — see [`docs/`](docs/README.md).\n\n\u003ca id=\"contributing\"\u003e\u003c/a\u003e\n## 🤝 Contributing\n\n[![Contribute](https://www.eclipse.org/che/contribute.svg)](https://workspaces.openshift.com#https://github.com/manusa/ai-beacon)\n\n\u003ca id=\"license\"\u003e\u003c/a\u003e\n## 📜 License\n\n[Apache License 2.0](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmanusa%2Fai-beacon","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmanusa%2Fai-beacon","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmanusa%2Fai-beacon/lists"}