{"id":51201063,"url":"https://github.com/runos-official/nodeagent","last_synced_at":"2026-06-28T00:30:24.642Z","repository":{"id":366136826,"uuid":"766503295","full_name":"runos-official/nodeagent","owner":"runos-official","description":"RunOS node agent: the per-node daemon that joins your machines to a RunOS-managed Kubernetes cluster. Source-available (Elastic License 2.0).","archived":false,"fork":false,"pushed_at":"2026-06-20T11:25:49.000Z","size":170,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-06-20T13:19:49.866Z","etag":null,"topics":["kubernetes","node-agent","runos","source-available","wireguard"],"latest_commit_sha":null,"homepage":"https://runos.com","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/runos-official.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-03-03T12:59:29.000Z","updated_at":"2026-06-20T11:25:45.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/runos-official/nodeagent","commit_stats":null,"previous_names":["runos-official/nodeagent"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/runos-official/nodeagent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/runos-official%2Fnodeagent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/runos-official%2Fnodeagent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/runos-official%2Fnodeagent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/runos-official%2Fnodeagent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/runos-official","download_url":"https://codeload.github.com/runos-official/nodeagent/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/runos-official%2Fnodeagent/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34873663,"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-06-27T02:00:06.362Z","response_time":126,"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":["kubernetes","node-agent","runos","source-available","wireguard"],"created_at":"2026-06-28T00:30:22.454Z","updated_at":"2026-06-28T00:30:24.615Z","avatar_url":"https://github.com/runos-official.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# RunOS Node Agent\n\nThe node agent (`runos`) is the small daemon you install on each machine you want\nto add to your [RunOS](https://runos.com)-managed Kubernetes cluster. It runs on\nyour hardware, joins the machine to your cluster, and keeps it connected and\nhealthy.\n\nIt only ever dials **out** to the RunOS control plane over an encrypted,\nmutually-authenticated link, so there are no inbound ports to open. A machine\nbehind NAT or a home/office firewall works without any port forwarding.\n\n## What it does for you\n\n- **Joins the machine to your cluster** and installs the Kubernetes bits it\n  needs.\n- **Connects your nodes with an encrypted overlay network** (WireGuard), so they\n  reach each other even across NAT and different networks.\n- **Keeps the Kubernetes API reachable** through a local load balancer, so the\n  cluster stays usable as nodes come and go.\n- **Reports health** back to the control plane and **updates itself** to the\n  version the control plane has selected.\n\n## How it works\n\nThe node agent holds one long-lived, mutually-authenticated connection to the\nRunOS control plane. The control plane sends it instructions (\"join the cluster\",\n\"set up the network\", \"update yourself\") and the agent carries them out on the\nmachine, then reports back. Nothing reaches the node except over that one\nauthenticated, outbound link.\n\n```\n        mutually-authenticated link (agent dials out, no inbound port)\n  RunOS control plane  \u003c───────────────────────────►  node agent\n                                                       (on your machine)\n```\n\nThe full transport detail and the complete instruction set live in\n[docs/architecture.md](docs/architecture.md).\n\n## Requirements\n\n- Linux (Ubuntu 24.04 recommended), `amd64` or `arm64`\n- Root access (it installs system packages and manages networking)\n- Outbound network access to the RunOS control plane and installer\n\n## Installing\n\nWhen you add a node in the RunOS console or CLI, you get a one-line install\ncommand to run on the machine. That command downloads the agent, registers the\nnode, and starts it as the `runos.service` systemd unit. See\n[docs/getting-started.md](docs/getting-started.md) for the full walkthrough.\n\nThe agent ships as attested Linux binaries on\n[GitHub Releases](https://github.com/runos-official/nodeagent/releases); the\ninstaller downloads the exact release the control plane has selected and verifies\nits checksum before installing it to `/usr/local/bin/runos`.\n\n## Updating\n\n```bash\nrunos update                     # update to the version the control plane advertises\nrunos update --version v0.24.0   # pin to an exact release\n```\n\nWhich version a node should run is decided by the RunOS control plane, so a plain\n`runos update` moves you to the version selected for your cluster.\n\n## Security\n\nThe agent talks to the control plane over mutual TLS only and holds no inbound\nlistener for control traffic. Released binaries carry a keyless Sigstore\nbuild-provenance attestation, so you can verify any binary came from this\nrepository's pipeline:\n\n```sh\ngh attestation verify nodeagent-linux-amd64 --repo runos-official/nodeagent\n```\n\nBecause the agent manages the machine on the control plane's behalf, it runs with\nroot and broad node access. See [SECURITY.md](SECURITY.md) for the trust model,\nwhat that means for you, and how to report a vulnerability.\n\n## Documentation\n\n- [docs/getting-started.md](docs/getting-started.md) — install and first run\n- [docs/architecture.md](docs/architecture.md) — how it works, in depth\n- [docs/configuration.md](docs/configuration.md) — configuration and hosts\n- [docs/commands.md](docs/commands.md) — command reference\n- [docs/troubleshooting.md](docs/troubleshooting.md) — diagnosing problems\n- [SECURITY.md](SECURITY.md) — security model and reporting\n- [CONTRIBUTING.md](CONTRIBUTING.md) — building, testing, and releasing\n- [CHANGELOG.md](CHANGELOG.md) — release history\n\n## License\n\nThe RunOS node agent is **source-available** under the\n[Elastic License 2.0](LICENSE): the source is published for transparency and\nsecurity review, not as open source. Use is subject to the license terms. See\n[LICENSE](LICENSE) and [NOTICE](NOTICE). Copyright 2026 RunOS.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frunos-official%2Fnodeagent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frunos-official%2Fnodeagent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frunos-official%2Fnodeagent/lists"}