softwarity/plug

plug

Run a local process as a member of your cluster: it resolves cluster service names, reaches cluster services, and is itself reachable in the cluster under a name — with no code change and no proxy settings in your app.

plug -s my-app:8080:3000 npm run start:dev
# reaches cluster services by name — and is itself reachable in the cluster
# as my-app:8080, forwarded to its local :3000

Prefix any command with plug and it joins the cluster by name — Node, the JVM, Python, Go, curl, gRPC, database drivers, anything. Stop the command and your machine is exactly as it was.

What you get

• Reach cluster services by their real names, from your laptop — no port-forwards

to wire up, no localhost:PORT mappings, no /etc/hosts edits.

• Be reachable in the cluster under your own name — workloads call my-app:8080

and land on your local process, for the life of the session.

• Works with any language or tool, unchanged — your app's sockets are never touched.
• Runs on Linux, macOS and Windows.
• Several clusters at once, side by side.
• Set up once per cluster, then no sudo or admin for daily use.

Install

Two pieces: a small agent in the cluster, and the plug CLI on each dev machine.

In the cluster — add the agent to the stack you want to reach:

services:
  plug:
    image: docker.io/softwarity/plug:latest
    ports: ["2222:22"]
    # required — the agent creates your -s name through it (see below)
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    # Swarm only, for -s: the signpost is a service, so run the agent on a
    # manager (any single-node swarm node IS a manager) as a single replica.
    # Ignored by plain Compose.
    deploy:
      replicas: 1

constraints: [node.role == manager]

The socket line is **required** on Docker, Compose and Swarm: it is how the
agent creates your `-s` name. It is root on the host, so mount it only on a
cluster you trust — the trust plug's no-auth transport already assumes.
Kubernetes needs no socket: the bundled manifest grants a Services-only RBAC
role instead — see [below](#the-name-in-the-cluster).

Standalone agent, or Kubernetes: see the [documentation](https://softwarity.github.io/plug/).

**On your machine** — install straight from the cluster, in one line.

Linux and macOS:

ssh -p 2222 -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null get@<cluster-host> install | sh

Windows, from Git Bash: