# k3sup: install k3s over SSH and get a kubeconfig back > A Go binary that SSHes into a host, runs Rancher's k3s installer, pulls the kubeconfig back to your laptop, and can join extra agents. Small tool, clear job. **alexellis/k3sup** — bootstrap K3s over SSH in < 60s 🚀 - Repository: https://github.com/alexellis/k3sup - Website: https://github.com/sponsors/alexellis - Stars: 7,442 · Forks: 433 - Language: Go - License: NOASSERTION - Published: 2026-10-06 · Updated: 2026-10-06 · Language: en - Canonical page: https://hysenlabs.com/projects/alexellis-k3sup ## Four commands that cover most installs The surface area is small enough to read in one screen. `k3sup install` provisions a server node, `k3sup join` adds agents to a cluster that already exists, `k3sup install --local` skips SSH entirely for the machine you are sitting at, and the Pro edition adds `get-config` for pulling a kubeconfig out of a cluster you did not create. ```bash k3sup install k3sup join k3sup install --local ``` The README's own framing of the goal is time, not capability: once a VM exists, k3sup should put you about sixty seconds away from running `kubectl get pods` on your own machine. That is the whole pitch. It is not trying to be a cluster lifecycle manager, and it is not trying to replace Terraform or a cloud provider's managed Kubernetes offering. The README does ask the obvious question on your behalf, whether a tool like this needs to exist when you can do the same thing with bash. The answer it gives is that the manual process is confusing for developers who are short on time, which is a fair description of the k3s install-and-kubeconfig-fetch dance rather than an argument that bash is wrong. ## What happens during an install over SSH The mechanism is worth knowing because it explains most of the requirements. k3sup SSHes into the remote host, installs k3s using the utility script from Rancher, passes a flag carrying the host's public IP so that TLS works properly, then fetches the `kubeconfig` file off the server and rewrites it so that your laptop can talk to the cluster. That third step is the part people underestimate. A kubeconfig as written on the server points at loopback, so without the rewrite a perfectly good cluster looks unreachable from your laptop. Fetching and patching it in one step is the reason this tool saves time rather than just wrapping a download. The ASCII diagram in the README spells out the same four phases: install via SSH, kubeconfig fetched automatically, agents joined via SSH, then kubectl usable from the laptop. Because the tool only ever needs SSH access and its own binary, that is the entire dependency list for the client side. The README also positions the tool as running from your local machine without ever logging into a remote server yourself. It lists targets including bare metal, Raspberry Pi, AWS EC2, Google Cloud, DigitalOcean, Civo, Linode and Scaleway, which is a list of places you can SSH to rather than a list of integrations. ## Cross-compiled in Go, cobra CLI, vendored dependencies The repository is a conventional Go CLI. `go.mod` names the module `github.com/alexellis/k3sup` and requires Go 1.26.0, which matches the 0.13.13 release note, which says it bumps go modules and GitHub Actions to Go 1.26. The CLI framework is `github.com/spf13/cobra` at v1.10.2, with `alexellis/go-execute/v2` for shelling out and `mitchellh/go-homedir` for locating your home directory, which is where the fetched kubeconfig ends up. The layout is the usual shape: `main.go` at the root, `cmd/` for the command tree, `pkg/` for the logic, `docs/` for documentation and assets, `hack/` for shell helpers, and a committed `vendor/` directory. Building is a Makefile affair. `make dist` produces binaries for linux amd64, armhf and arm64, darwin amd64 and arm64, and windows, with the version and commit stamped in through `-ldflags`: ```bash CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -ldflags $(LDFLAGS) -o bin/k3sup ``` There is also `make test`, which runs `go test` with coverage across the module excluding vendor, and a `make gofmt` target that fails the build on formatting drift. A `get.sh` at the repository root is the install script, and `.DEREK.yml` points at the maintainer's own release automation, which is worth knowing if you are tracking who ships the binaries. ## Community Edition against the paid Pro split This is the part of the project that needs reading carefully, because the free tool and the commercial one have different scopes. The README describes the Community Edition as ideal for experimentation and says k3sup-pro was built to satisfy long-standing requests for an IaaC and GitOps experience. What Pro adds is a `plan` and `apply` pair that automates installs in parallel, small or large, with a plan file you can customise and keep in Git for maintenance and updates. It also adds rapid uninstallation and reset through `k3sup-pro uninstall`, a `pro exec` command to run a command everywhere, and `pro get-config` to pull a kubeconfig from an existing cluster. ```bash k3sup-pro plan k3sup-pro apply k3sup-pro exec k3sup-pro get-config ``` Those four commands are the boundary. If your task is one server and a couple of agents, the Community Edition covers it and you never touch Pro. If your task is a fleet that has to be rebuilt from a file in Git on a schedule, that is what you are paying for. One detail to keep straight: the Pro binaries are obtained separately, so `k3sup` and `k3sup-pro` are two different executables rather than one with a feature flag. Check what is on your PATH before assuming a subcommand exists. ## What k3sup does not configure for you The README's table of contents lists a Caveats on security section, a troubleshooting section, notes on getting access to your kubeconfig, a section on smart cards and 2FA, and a note on iptables. The existence of those headings is itself useful: they tell you the areas where this workflow is known to be fiddly. The iptables note in particular matters for anyone running k3sup on a cloud VM, because container networking rules are exactly the kind of thing that differs between a provider's default image and your own. The smart card and 2FA section exists because your SSH key may live in a hardware token or an agent, and k3sup needs to be able to use it non-interactively. Two other things the tool deliberately leaves alone. The README mentions Highly-Available multi-master setups with either external SQL or embedded etcd, but the clustering is still your design decision; k3sup carries out the SSH calls you asked for rather than choosing topology for you. And the use-case list explicitly includes cloud-init and CI, which means the same command can be run from a provisioning pipeline, but nothing in the repository automates it for you. The Raspberry Pi micro-tutorial in the README exists for the same reason: getting from a fresh board to a working node is a supported path, and it is one of the cases where the convenience is largest because the manual steps on a Pi are the least pleasant. ## Release cadence, licensing and the rough edges Three releases are visible. Version 0.13.11 on 2025-08-20 added K3sup Pro to the README along with the `k3sup pro get` command, 0.13.12 on 2026-03-04 is described only as clarity and updates, and 0.13.13 on 2026-09-03 bumps go modules and GitHub Actions to Go 1.26. The last push to the repository was on 2026-09-03, the same day as that release. The 0.x version number is the honest signal here: this is a tool people depend on, but the author is not claiming API stability. Licensing needs a second look. The repository metadata reports no recognised licence, while the README carries an MIT badge and the tree holds both a `LICENSE` file and an `EULA.md`. The presence of a separate EULA alongside an MIT LICENSE is the combination to examine yourself before putting this in a company pipeline, particularly if you plan to use the Pro edition. The other rough edge is the homepage field, which points at the author's GitHub sponsors page rather than a documentation site. All real documentation lives in the README itself, and the README leans on it heavily with a long table of contents. That makes the repository the place to read, and it also means the FAQ at the bottom of the README is where you will find the answers the table of contents promises. Compared with the alternatives, the honest framing is this: a plain bash script or the k3s install command plus a manual `scp` of the kubeconfig will do the same job for one server. k3sup wins when you are doing this repeatedly, on several hosts, possibly from CI, and you want the kubeconfig rewriting to be consistent every time rather than something you retype. ## Conclusion k3sup earns its place when the thing standing between you and a working cluster is a copy-and-paste install script with a public IP flag you always forget. It does one job, it does it over plain SSH, and it hands back a kubeconfig that kubectl can use. It does not configure DNS, TLS offload, ingress controllers or storage, and the README leaves those to you. Check that your target host is reachable as a non-root user with sudo before you start, remember that the Pro edition is a separate download, and try `k3sup install --local` on a spare machine first, since that path skips SSH and gives you the fastest way to see whether the rest of the flow works. ## FAQ ### Is K3s the same as Kubernetes? k3sup does not install Kubernetes directly, it installs k3s so that you end up with a working kubectl. The README describes the goal as bootstrapping Kubernetes with k3s onto any VM, and fetching the kubeconfig back to your laptop is the step that makes a real cluster reachable from where you are sitting. ### What do I need before running k3sup install? SSH access to the remote host and the k3sup binary on your own machine. The tool SSHes in, runs Rancher's k3s utility script with a flag carrying the host's public IP so TLS works, then fetches and rewrites the kubeconfig. ### How do I add more nodes to a k3sup cluster? Use `k3sup join`, which joins existing Linux hosts into a k3s cluster as agents over SSH. If you are on the machine itself rather than a remote host, `k3sup install --local` bypasses SSH entirely. ### What is the difference between k3sup and k3sup-pro? k3sup is the Community Edition, described in the README as ideal for experimentation, and handles single server installs plus agent joins. k3sup-pro adds a plan and apply pair for parallel installs kept in Git, along with uninstall, `pro exec` and `pro get-config`, and it is a separate binary. ## Sources - [alexellis/k3sup on GitHub](https://github.com/alexellis/k3sup) - [Issues](https://github.com/alexellis/k3sup/issues) - [Project website](https://github.com/sponsors/alexellis) - [README](https://github.com/alexellis/k3sup/blob/master/README.md) - [Releases](https://github.com/alexellis/k3sup/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/alexellis-k3sup