Connectors

Connectors

Connectors let CronCompose see and manage service managers that already run on a target: web servers, process managers, containers. The agent discovers what is installed, reads live status and config, and (with enough privilege) edits config and drives lifecycle — all from the portal, over the existing outbound gRPC stream. No new inbound access.

Full design: docs/connectors.md.

Goals

• Discover installed service managers automatically.
• Show live status (running/stopped, version, object counts) and current configuration.
• Edit configuration safely: validate before activating, back up before writing, roll back on failure.
• Drive start / stop / restart / reload / enable / disable.
• Keep the agent unprivileged by default; privileged actions go through a narrow, explicit, per-connector allowlist.
• Reuse transport, audit log, and RBAC. Add no new daemons.

Non-goals

• Installing or removing the underlying software.
• Cross-server templating or fleet rollout (one connector instance at a time).
• A vendor-aware config IDE. Validation is delegated to each tool (nginx -t, and so on).

Concepts

Term	Meaning
Connector	One integration on one server, e.g. nginx on web-01. Identified by (server_id, kind, instance).
Resource	config_file (editable text + validator + reload) or object (lifecycle unit: systemd unit, Docker container, pm2 process).
Snapshot	Immutable backup of a config file, taken before every write. Mirrors job versions: never mutate in place.
Operation	One read / validate / apply / lifecycle / rollback. Persisted like a run, with step-by-step output.
Capabilities	Booleans reported at discovery (manages_config, can_validate, can_reload, …). The UI only offers what the agent can actually do.

Implemented today

Kind	Detect	Config	Validate	Activate	Objects
nginx	nginx -v	/etc/nginx/**	nginx -t	reload	none
systemd	systemctl --version	unit files / drop-in overrides	systemd-analyze verify	daemon-reload then reload/restart	units
Docker	docker version	compose files	docker compose config -q	up -d / container restart	containers
pm2	pm2 --version (per user)	ecosystem / pm2 save dump	JSON on start	reload/restart	processes

Ports page

The Ports sidebar lists TCP listen sockets owned by systemd or pm2. Each connector also has a Ports tab. You can label sockets (stored on the control plane) and Close a port — that stops the owning unit or pm2 process, not a raw kill.

How the agent finds sockets (since v0.0.3):

1. ss -lntp, then lsof if ss omits PIDs (common when the agent is unprivileged).
2. Retry with passwordless sudo for ss / lsof when sudoers allows it.
3. Map PIDs to owners: systemd via systemctl show + cgroup PIDs; pm2 via jlist + child processes.

If the page is empty but connectors show services running, re-run the installer or sudo ./install/lib/agent_sudoers.sh <agent-user>. See Operations — socket inspection.

Install	Typical agent user	Sudoers
scripts/install-agent.sh	croncompose	automatic
Source install (pm2 on a Pi)	your login user (e.g. pi)	./install/install.sh or agent_sudoers.sh

Designed, not implemented

Apache, Caddy, Traefik, HAProxy, system cron, ufw. The tables and security notes are in the repo spec. Extra guardrails are already specified for ufw (must not drop the control path) and cron (overlaps CronCompose’s own jobs).

Access control

• Viewer: list connectors, status, operations history, ports.
• Operator: lifecycle actions (start/stop/…), port labels.
• Admin: read and write config bytes, snapshots, restore.

Every mutating call is audited. Apply uses base_checksum so a concurrent edit is refused rather than overwritten.

How it moves on the wire

Connector requests are commands on the same AgentStream as jobs. If the agent is offline, the control plane records offline and returns 503. Results are stored as operations so the browser can leave and still see how it ended.