feat: agent runs as system service via kardianos/service

Integrate github.com/kardianos/service so the Go agent can install itself
as a system service (launchd on macOS, systemd on Linux, Windows service).

Three CLI modes:
- No args: interactive setup wizard that registers, installs, and starts
  the service — the friend-friendly double-click path
- --run: foreground mode for Docker/service manager/development
- --service <action>: power-user install/uninstall/start/stop/restart/status

Automatically requests sudo when elevation is needed. Bakes PLOW_DATA_DIR
into the service env so the daemon finds credentials generated by the
installing user. Clears stale service state before reinstalling to avoid
launchd throttle errors from prior crash loops.

Author: jackharrhy

.gitignore

@@ -10,3 +10,4 @@ dist/
 src/where_the_plow/static/changelog.html
 tmp
 agent/plow-agent
+.DS_Store

agent/Dockerfile

@@ -1,11 +1,11 @@
-FROM golang:1.22-alpine AS builder
+FROM golang:1.25-alpine AS builder
 WORKDIR /build
-COPY go.mod ./
+COPY go.mod go.sum ./
 RUN go mod download
 COPY *.go ./
 RUN CGO_ENABLED=0 go build -ldflags="-s -w" -o /plow-agent .
 
 FROM scratch
 COPY --from=builder /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/
 COPY --from=builder /plow-agent /plow-agent
-ENTRYPOINT ["/plow-agent"]
+ENTRYPOINT ["/plow-agent", "--run"]

agent/README.md

@@ -15,21 +15,55 @@ The city publishes real-time plow locations on their [AVL map](https://map.stjoh
 
 Your credentials are stored locally and reused on subsequent runs. The agent uses minimal resources and runs quietly in the background.
 
-## Running
+## Quick start (recommended)
 
-### Binary
+Download the latest release for your platform, then just run it:
 
-Download the latest release for your platform, then:
+```
+./plow-agent
+```
+
+This launches an interactive setup wizard that:
+1. Asks for the server URL (defaults to `https://plow.jackharrhy.dev`)
+2. Prompts for a name to identify your agent (e.g. "alice-laptop")
+3. Generates your cryptographic keypair
+4. Registers with the server
+5. Installs itself as a **system service** (systemd on Linux, launchd on macOS, Windows service)
+6. Starts the service automatically
+
+After setup, the agent runs in the background and survives reboots. You don't need to keep a terminal open.
+
+**Note:** Installing a system service usually requires administrator/root privileges. On Linux, run with `sudo`. On macOS, you may get a permissions prompt. On Windows, run as Administrator.
+
+## Running interactively
+
+If you prefer not to install a service (or for Docker/development use):
+
+```
+./plow-agent --run --server https://plow.jackharrhy.dev
+```
+
+This runs the agent in the foreground. Press Ctrl+C to stop.
+
+## Managing the service
+
+Once installed, you can control the service with:
 
 ```
-./plow-agent --server https://plow.jackharrhy.dev
+plow-agent --service status      # Check if running
+plow-agent --service stop        # Stop the service
+plow-agent --service start       # Start the service
+plow-agent --service restart     # Restart the service
+plow-agent --service uninstall   # Remove the service
 ```
 
-On first run it will ask for a name to identify your agent (e.g. "alice-laptop"). The keypair and name are saved to `~/.config/plow-agent/` so you only do this once.
+### Viewing logs
 
-That's it. Leave it running and the server operator will approve you.
+- **Linux (systemd):** `journalctl -u plow-agent -f`
+- **macOS (launchd):** `log show --predicate 'process == "plow-agent"' --last 1h`
+- **Windows:** Event Viewer > Application logs
 
-### Docker
+## Docker
 
 ```
 docker run -d \
@@ -48,7 +82,7 @@ To build the image yourself:
 docker build -t plow-agent agent/
 ```
 
-### Kubernetes
+## Kubernetes
 
 A ready-made manifest is included at [`k8s.yaml`](k8s.yaml). Edit `PLOW_NAME` to your name, then:
 
@@ -62,9 +96,11 @@ This creates a small PVC for key persistence and a Deployment running the agent.
 
 | Flag / Env Var | Required | Description |
 |---|---|---|
-| `--server` / `PLOW_SERVER` | Yes | Plow server URL |
+| `--server` / `PLOW_SERVER` | Yes (for `--run`) | Plow server URL |
+| `--run` | No | Run in foreground instead of installing as service |
+| `--service <action>` | No | Control installed service: install, uninstall, start, stop, restart, status |
 | `PLOW_NAME` | Docker/K8s only | Agent name (binary prompts interactively) |
-| `PLOW_DATA_DIR` | No | Override config directory (default: `~/.config/plow-agent/`, or `/data` when `PLOW_DATA_DIR` is set) |
+| `PLOW_DATA_DIR` | No | Override config directory (default: `~/.config/plow-agent/`, or `/data` when set) |
 
 ## What gets stored locally
 

agent/go.mod

@@ -1,3 +1,8 @@
 module github.com/jackharrhy/plow-agent
 
 go 1.25.6
+
+require (
+	github.com/kardianos/service v1.2.4 // indirect
+	golang.org/x/sys v0.34.0 // indirect
+)

agent/go.sum

@@ -0,0 +1,4 @@
+github.com/kardianos/service v1.2.4 h1:XNlGtZOYNx2u91urOdg/Kfmc+gfmuIo1Dd3rEi2OgBk=
+github.com/kardianos/service v1.2.4/go.mod h1:E4V9ufUuY82F7Ztlu1eN9VXWIQxg8NoLQlmFe0MtrXc=
+golang.org/x/sys v0.34.0 h1:H5Y5sJ2L2JRdyv7ROF1he/lPdvFsd0mJHFw2ThKHxLA=
+golang.org/x/sys v0.34.0/go.mod h1:BJP2sWEmIv4KK5OTEluFJCKSidICx8ciO85XgH3Ak8k=

agent/k8s.yaml

@@ -27,7 +27,7 @@ spec:
       containers:
         - name: plow-agent
           image: ghcr.io/jackharrhy/plow-agent:latest
-          args: ["--server", "https://plow.jackharrhy.dev"]
+          args: ["--run", "--server", "https://plow.jackharrhy.dev"]
           env:
             - name: PLOW_NAME
               value: "your-name-here"