ServerKit/docs/COEXISTENCE.md

Running ServerKit alongside another control panel

Plan 27. The honest answer to "can this panel manage / migrate my existing box?" — including what it will and won't do while another panel is still in charge.

ServerKit has three explicit adoption modes. Pick the one that matches where the box is today; you can move between them as you migrate.

1. Observe — read-only, safe to run anywhere

Install the agent on any Linux box, including one still run by another control panel, and set the server to Observed. You get:

• Metrics — CPU / memory / disk / network, like any paired server.
• A read-only survey ("flight") — a map of what's running: web servers and their virtual hosts (domain → document root / upstream), databases, TLS certificates, cron jobs, listening ports, and a flag if another control panel is detected. See the read-only guarantees below.
• Doctor probes — the read-only health checks.
• Backups of paths you explicitly point at.

You do not get, by design:

• Site creation or web-server config writes.
• Any mutating server-targeted action. These are refused server-side — the server list and detail page show an Observed chip and a read-only banner, and the agent command choke point returns a clean refusal rather than letting two panels fight over the same files. Every refusal is recorded in the server's audit trail, and the Survey tab shows a blocked-commands counter.
• Agent binary updates. Observe mode covers the agent itself: agent:update is refused too, so observing never silently re-flashes the box. If you do want to keep the agent current while observing, set the per-server "allow agent updates while observing" break-glass on the Survey tab — an explicit, audited opt-in, off by default.

What an Observed server still allows (all reads): system metrics/info/processes, Docker/compose list/inspect/logs/stats, file read/list within allowed paths, the survey, doctor probes, agent:recapabilities (capability re-discovery), and backups of paths you point at.

Why the hard line: two panels writing the same web-server config (nginx / Apache vhosts, PHP-FPM pools, TLS) will overwrite each other and eventually break the site. That scenario is never supported. Observe mode exists precisely so you can adopt a box for visibility without stepping on the panel that currently owns its config.

Detection only ever suggests. If the survey finds another panel's marker, ServerKit shows a one-click "switch to Observed" prompt — it never flips a managed server automatically, and it never downgrades an existing managed box.

The survey's read-only guarantees

The survey is driven by a shipped, versioned probe catalog you can read in full (the Survey tab's "What we check" view lists every location verbatim). The agent enforces the trust boundary with a fixed allowlist of read-only primitives — file-exists, glob, unit status, socket list, process list, and parse-light extraction of a few config directives (server_name, root, proxy_pass, and equivalents). Concretely:

• Credential and environment files are listed by path only — never read.
• No file contents leave the box beyond those parse-light directive lines.
• The catalog can only combine those primitives; it can never name a command to run. A compromised panel can at worst enumerate paths — never execute.

Full agent contract: AGENT_SURVEY_SPEC.md.

2. Migrate — the guided path off the other panel

When you're ready to move a site onto ServerKit:

1. Survey the box (Observe mode) so you can see every site, its document root, and its databases.
2. Import each site. From the Survey tab, "Migrate this site" pre-fills the import wizard with the domain and document root. Imports cover files + MySQL databases + database users (password hashes preserved) + crontabs — from a control-panel backup archive, or a live pull over SSH for panel-less boxes. Mail accounts and DNS zones are not migrated (they stay on the source until moved separately).
3. Verify on ServerKit using a staging domain / basic-auth before touching public DNS; WordPress sites get the URL-swap tool for post-move URL fixes.
4. DNS cutover, reversible per domain. Before changing any record, ServerKit snapshots the domain's existing records (name / type / content / TTL). Lower the TTL a step ahead, switch the record, verify propagation, and revert from the snapshot in one click if anything looks wrong.
5. Decommission. Once every surveyed site is migrated, ServerKit shows a checklist: what to stop on the old box, what to keep until TTLs expire, and when it's safe to wipe.

3. Manage — full takeover on a clean box

Today's normal mode: ServerKit owns the box and manages the web stack end to end. This is the right mode for a fresh server, or for one you've finished migrating off its previous panel and cleaned up.

What is never supported

• Two panels writing the same web-server config. Keep exactly one owner of nginx/Apache/PHP-FPM/TLS per box. Use Observe (read-only) until ServerKit is that single owner.
• Mail and DNS-zone migration are not part of v1 imports (the future path is the mail extension + DNS zone rails).