RustProxy/docker-agent

RustProxy Docker Agent

Small read-only discovery service for Docker hosts. It talks to the local Docker Engine Unix socket, reports running containers with non-loopback published TCP ports, preserves every host binding for each service, and exposes the inventory to RustProxy through a Bearer-token protected HTTPS endpoint.

The inventory also reports multiple usable host addresses: active host interface addresses, the primary routed address, an optional public-IP lookup result, and the optional advertised/preferred address. Loopback/link-local and obvious Docker-generated bridge/veth interfaces are omitted from the host-address list.

TLS by default

HTTPS is enabled by default. On first start the agent creates a persistent ECDSA P-256 self-signed certificate under /var/lib/rustproxy-docker-agent/ and reuses it across restarts. The private key is written with mode 0600.

The installer prints the certificate SHA-256 fingerprint. Configure that fingerprint in RustProxy -> Settings -> Docker agents. RustProxy then pins the exact agent certificate while still verifying the TLS handshake signatures. A changed/replaced certificate is rejected until the configured fingerprint is updated.

Show the current fingerprint again with:

sudo rustproxy-docker-agent --print-fingerprint

If you replace the generated certificate with one signed by a normal public CA, the fingerprint field in RustProxy may be left empty so standard CA/hostname validation is used. Plain HTTP is available only when RUSTPROXY_DOCKER_AGENT_TLS=false; it is not the default.

Quick install on systemd

sudo ./install.sh

The installer runs tests, builds the binary, creates the service account, writes a random token on first install, installs the hardened unit, starts it and prints the TLS fingerprint.

Build manually

go test ./...
go build -trimpath -ldflags='-s -w' -o rustproxy-docker-agent .

systemd

1. Create a dedicated rustproxy-docker-agent system user and grant it read access to the Docker socket (commonly by membership in the docker group). Docker socket access is privileged; isolate this account and the host firewall.
2. Copy the binary to /usr/local/bin/rustproxy-docker-agent.
3. Copy docker-agent.env.example to /etc/rustproxy/docker-agent.env, generate a long random token and bind only to an address reachable by RustProxy.
4. Ensure /var/lib/rustproxy-docker-agent is writable only by the service identity. The shipped systemd unit creates it through StateDirectory=.
5. Copy rustproxy-docker-agent.service to /etc/systemd/system/, then run systemctl daemon-reload && systemctl enable --now rustproxy-docker-agent.

The inventory endpoint is GET /v1/inventory with Authorization: Bearer <token>. /healthz does not expose Docker inventory. Both are served over HTTPS by default.

RUSTPROXY_DOCKER_ADVERTISE_IP marks a preferred address but does not suppress automatic discovery of the host's other addresses. RUSTPROXY_DOCKER_PUBLIC_IP_URL adds the externally observed address when enabled. RustProxy can choose a concrete reported address independently for every Docker-backed vhost.