" --reason "..." # suppress a greenlight false positive fleet audit ignores # list audit ignore rules ``` Greenlight runs a corpus of App Store Review Guideline checks against the project source. Findings classified as "confirmed false positive" are suppressed via the ignore list so the next run is noise-free; everything else fails the audit. Useful as a pre-flight before each TestFlight publish. ## Cloudflare guard `fleet guard` installs a watchdog layer that detects unauthorised dashboard changes and DNS drift on protected Cloudflare zones. ``` sudo fleet guard install # install scripts + cron + log rotation fleet guard status # show what's protected and the last check time fleet guard approve <change-id> # acknowledge a flagged change as intentional fleet guard reject <change-id> # treat a flagged change as compromise ``` Components installed under `/usr/local/sbin`: - **`cf-snapshot`** — periodic snapshot of the Cloudflare zone configuration (DNS, page rules, WAF settings) to `/var/lib/cf-snapshots/` - **`cf-audit-monitor`** — diffs the latest snapshot against the previous and surfaces unauthorised changes for operator approval - **`dns-drift-watch`** — detects when DNS records drift from the snapshot (cron, alerts via the same channels as `fleet watchdog`) - **`cert-expiry-watch`** — flags certs approaching expiry across all protected hosts - **`fleet-guard` / `fleet-guard-execute`** — the orchestrator + executor pair, run as the `fleet-guard` system user with no shell ## App onboarding Registering an app is step one, not the finish line — a registered app still needs a systemd unit, vault keys for anything its compose file interpolates or feeds into build args, an unsealed runtime env, and nginx configs for its domains. Two commands close that gap: **`fleet onboard <app> [--json]`** prints the full readiness checklist: registry entry, compose analysis (required vs defaulted env vars, build args, host-port clashes with other registered apps, project-name collisions on a shared compose directory), systemd unit, vault key-name coverage (names only — values are never read), the materialised runtime env file, nginx per domain, and whether the app's port answers locally. Every failed check comes with the exact fix command and who can run it (`mcp-callable`, `cli`, or `operator, root shell`). Exits non-zero when a blocking check is missing, so scripts and agents can gate on it. Also available as the read-only `fleet_onboard` MCP tool, and both `fleet add` and `fleet_register` append the unresolved items to their output. **`fleet service install <app> [--force]`** scaffolds the systemd unit for a registered app from its trusted registry fields (working directory, compose file, database dependency) — the path for apps registered under a custom name or compose file, which `fleet add` never covers. Template-only generation, refuses to overwrite an existing unit without `--force`. Also available as the `fleet_service_install` MCP tool. `fleet deploy` runs the blocking subset as a preflight before the build (unit exists; compose-required env vars have a vault entry and an unsealed runtime env file), so a doomed deploy fails immediately with the fix commands instead of dying mid-build with a bare npm/docker error. Apps whose compose needs nothing deploy exactly as before. ## Deployment Flow ```mermaid graph TD Deploy["fleet deploy app|dir"] Deploy --> Register{"Already\nregistered?"} Register -->|No| Add["Register app"] Register -->|Yes| Build Add --> Build["docker compose build"] Build --> Start{"Service\nrunning?"} Start -->|No| StartSvc["systemctl start"] Start -->|Yes| Restart["systemctl restart"] StartSvc --> Healthy["App deployed"] Restart --> Healthy ``` ## Boot Refresh On every systemd start — including reboots — Fleet pulls the latest code from GitHub and rebuilds the image if needed, before starting the container. The flow is entirely fail-safe: any failure at any step (dirty working tree, no remote, fetch error, non-fast-forward merge, build failure, or a 900-second wall-clock timeout) is logged and falls through to a plain `docker compose up` with the existing image. The container will always start. **New commands** | Command | Description | |---------|-------------| | `fleet boot-start <app>` | Entry point systemd now invokes (`ExecStart`). Runs refresh then `docker compose up`. Not typically run by hand. | | `fleet rollback <app>` | Re-tags `<image>:fleet-previous` → `<image>:latest` and restarts the service. Fleet tags the previous image automatically before every build. | | `fleet patch-systemd` | Brings every installed unit up to the current template: `ExecStart=fleet boot-start`, `TimeoutStartSec=900`, the start rate limit moved into `[Unit]`, the `ExecStartPre` compose-down teardown removed, and the `fleet-unseal` / `docker-databases` dependencies added where they apply. Backs the original up to `<path>.service.bak`, write-once. | | `fleet patch-systemd --rollback` | Restores all `.bak` unit files and runs `daemon-reload`. | **Kill switch** To disable boot refresh entirely — next `systemctl start` goes straight to `docker compose up`: ```bash sudo touch /etc/fleet/no-auto-refresh ``` Remove the file to re-enable. **Registry field: `lastBuiltCommit`** Each app in the registry stores the Git commit that was last built. Fleet sets this on `fleet deploy` and on every successful boot-refresh build. Boot refresh skips `docker compose build` when HEAD already matches this value, keeping boots fast when no code has changed. **First boot after upgrade** Any app with `lastBuiltCommit` unset will trigger a full rebuild the first time it boots after upgrading to this version. Expect a longer first boot for those apps. **Recovery escape hatches** | Situation | Action | |-----------|--------| | One app misbehaving after a build | `fleet rollback <app>` | | Registry corrupted | Auto-loads `.bak` on next read | | Broad issue with boot-start behaviour | `sudo touch /etc/fleet/no-auto-refresh` | | Worst case — revert all unit files | `fleet patch-systemd --rollback` | ## MCP Server Fleet exposes 50+ tools via the [Model Context Protocol](https://modelcontextprotocol.io/) for AI-assisted server management — the static surface (server.ts + git / secrets / deps / audit / testflight tool families) plus every migrated registry command exposed through the registry bridge. Run `fleet mcp` to start the stdio server, or install it into Claude Code: ```bash sudo fleet install-mcp ``` Tools cover the full surface area: app lifecycle, secrets, nginx, Git, health checks, and dependency monitoring. See the [MCP documentation](https://fleet.hesketh.pro/mcp/) for the complete tool list. ### Privilege-separated root daemon `fleet mcp` (stdio) runs in-process as whoever launched it, so privileged tools fail when that user is not root — and most fleet operators run their MCP client (e.g. Claude Code) as an ordinary user, not root. `fleet mcp install` sets up a privilege-separated alternative so an unprivileged client can drive the full toolset securely: - a **root daemon** (`fleet-mcp.service`) does all privileged work and is the only process that touches systemd / docker / nginx / the vault; - it listens on a unix socket (`/run/fleet-mcp/mcp.sock`) locked to `root:fleet-guard 0660`, so only root and members of the `fleet-guard` group can connect — the kernel is the access boundary; - the client runs `fleet mcp connect` as the ordinary user; it holds no privilege of its own and just shuttles bytes to the socket; - every tool call passes a **guard**: tier-based authorisation (`read`/`mutate`/`destructive`), per-tier rate limiting, and an append-only audit log at `/var/log/fleet-mcp/audit.log` with secret values redacted; - **destructive tools (deploy, start/stop/restart, rotate-key, git push/release) are denied by default** — opt in per tool in `/etc/fleet/mcp-policy.json`. ```bash # on the server (one command; idempotent) sudo fleet mcp install --write-client-config # sets up the daemon + patches ~/.claude.json # then log out/in so your shell picks up the fleet-guard group, and: fleet mcp doctor ``` Migration is non-breaking: bare `fleet mcp` keeps working exactly as before, so nothing changes until you opt in. To point an MCP client at the daemon manually, use: ```json { "mcpServers": { "fleet": { "command": "fleet", "args": ["mcp", "connect"] } } }</article></body></html>

{ "name": "poolside", "logging": { "redaction": { "enabled": true, "categories": { "ip": true, "email": false }, "customPatterns": [{ "name": "employee_id", "pattern": "EMP-\\d{6}" }], "allowlist": ["ops@fleet.internal", "/status-[0-9]+/"] } } } ``` - `allowlist` wins over everything, built-in and custom alike. It is the escape hatch when a false positive turns up in production — literal strings, or `/regex/flags`. - `customPatterns` redact capture group 1 when one is present, otherwise the whole match. They are screened for ReDoS shapes at load, capped at 32 patterns and 1000 chars each, not run against lines over 4096 chars, and never allowed to throw: a bad pattern is skipped with a warning and `fleet logs` keeps working. ### Egress observation (v1.6) ``` fleet egress observe # snapshot current outbound flows via nsenter+ss fleet egress show # show config + allowlist fleet egress allow # add to allowlist (supports *.host wildcards) ``` v1 is **observe-only** — it never blocks packets, so zero risk of breaking apps. Reads each container's network namespace via `nsenter` so it sees real container egress (not just host-side NAT'd flows). Reverse-resolves remote IPs to hostnames best-effort. RFC1918 destinations don't count as violations. `enforce` mode (actual default-deny via nftables) is deferred to a future phase — by design, it requires the operator to explicitly promote a shadow-clean app, never auto-promotes. ## Backups (off-host) ``` fleet backup init # initialise the restic repository fleet backup register [--paths …] # tell fleet which paths and dbs to capture fleet backup register-all # bulk-register every known app fleet backup snapshot [--tag …] # take an on-demand snapshot fleet backup snapshot-all # one snapshot per registered app fleet backup list [] # list snapshots, latest first fleet backup restore --snap --target fleet backup prune # apply retention policy fleet backup verify # restic check (data integrity) fleet backup integrity # repository integrity report fleet backup schedule --cron "..." # install a fleet-backup@.timer unit fleet backup schedule-all # bulk-install timers from registered apps fleet backup unschedule # remove the timer fleet backup status [] # last-snapshot age, sizes, append-only state fleet backup serve --port # browser-based restore explorer (see below) fleet backup test # end-to-end snapshot+restore smoke ``` Snapshots go to a restic backend mounted with `append-only` mode so a compromised host can't delete history. Database dumps stream straight into the snapshot via `dumpFileSpawn`, never landing on disk in plaintext. Backups are encrypted twice — restic at rest, plus per-app age encryption inside the snapshot for anything classified as sensitive. ### Restore explorer `fleet backup serve --port 7300` starts a localhost-bound HTTP service designed to live behind nginx. It serves: - a read-only status dashboard at `/backups` showing the latest snapshot per app and any retention lag - a tree explorer at `/backups/explore` for browsing snapshot contents - a per-file streaming endpoint that pipes `restic dump` straight to the browser - a one-click restore into a fresh timestamped staging dir under `/var/restore` Authentication is **TOTP only** — paste the secret into your authenticator app on setup (`fleet backup setup-totp`). Sessions are signed cookies (`fleet_backup_session`), `Secure; HttpOnly; SameSite=Strict; Path=/backups`. Sensitive paths (`.env`, age keys, private SSH keys) are classified server-side and refuse view/download regardless of who's logged in. CSRF posture: every `/api/*` request must carry `x-fleet-backup: 1` (a custom header browsers can't set cross-origin without preflight), and write methods (POST / DELETE) must additionally carry an `Origin` header whose host matches the deployment domain exactly. Read methods tolerate a missing `Origin` so curl probes still work. ## Routines `fleet routines` is a TUI for signal-based scheduled tasks. Each routine has: - a **target repo** the routine operates against - a **trigger condition** (signals: open issues count, failing checks, branch ahead of remote, custom git-clean signal, scheduled, manual) - a **runner**: `claude-cli` (drives a Claude Code session), `shell` (just runs a script), or `mcp-call` (invokes one MCP tool) - a **schema** that validates inputs before the runner sees them Routines run from a systemd-timer-driven service called `fleet-routine@.timer` — fleet ships the templates and `fleet routine-run --id ` is the headless entrypoint that timer fires. The TUI shows a signals grid (which routines are gated on what), a routine list, and per-routine run history. ``` fleet routines # interactive TUI fleet routine-run --id [--target ] [--trigger scheduled] [--json] ``` The claude-cli runner serialises through a `proper-lockfile` mutex so two routines targeting the same repo can't race each other, and respects an abort signal so a `systemctl stop` cleans up mid-run rather than orphaning a child process. ## Mobile pipelines For iOS/macOS apps, fleet drives both the build pipeline and the App Store compliance check. ### TestFlight publishing ``` fleet testflight publish # dispatch the macOS build workflow to TestFlight fleet testflight builds # list TestFlight builds for the app fleet testflight update --build --whats-new "..." fleet testflight delete --build # expire a TestFlight build fleet testflight doctor # check gh + App Store Connect credentials ``` The publish flow goes through a GitHub Actions macOS runner — fleet dispatches the workflow with the app's bundle ID and version, then polls until the build appears in App Store Connect. Auth uses an API key (issuer + key ID + p8) loaded via a fleet-managed secret. ### App Store compliance audit ``` fleet audit [target] # run greenlight against a mobile project fleet audit guidelines # browse App Store Review Guidelines (list/show/search) fleet audit doctor # check the greenlight binary is installed fleet audit ignore "" --reason "..." # suppress a greenlight false positive fleet audit ignores # list audit ignore rules ``` Greenlight runs a corpus of App Store Review Guideline checks against the project source. Findings classified as "confirmed false positive" are suppressed via the ignore list so the next run is noise-free; everything else fails the audit. Useful as a pre-flight before each TestFlight publish. ## Cloudflare guard `fleet guard` installs a watchdog layer that detects unauthorised dashboard changes and DNS drift on protected Cloudflare zones. ``` sudo fleet guard install # install scripts + cron + log rotation fleet guard status # show what's protected and the last check time fleet guard approve <change-id> # acknowledge a flagged change as intentional fleet guard reject <change-id> # treat a flagged change as compromise ``` Components installed under `/usr/local/sbin`: - **`cf-snapshot`** — periodic snapshot of the Cloudflare zone configuration (DNS, page rules, WAF settings) to `/var/lib/cf-snapshots/` - **`cf-audit-monitor`** — diffs the latest snapshot against the previous and surfaces unauthorised changes for operator approval - **`dns-drift-watch`** — detects when DNS records drift from the snapshot (cron, alerts via the same channels as `fleet watchdog`) - **`cert-expiry-watch`** — flags certs approaching expiry across all protected hosts - **`fleet-guard` / `fleet-guard-execute`** — the orchestrator + executor pair, run as the `fleet-guard` system user with no shell ## App onboarding Registering an app is step one, not the finish line — a registered app still needs a systemd unit, vault keys for anything its compose file interpolates or feeds into build args, an unsealed runtime env, and nginx configs for its domains. Two commands close that gap: **`fleet onboard <app> [--json]`** prints the full readiness checklist: registry entry, compose analysis (required vs defaulted env vars, build args, host-port clashes with other registered apps, project-name collisions on a shared compose directory), systemd unit, vault key-name coverage (names only — values are never read), the materialised runtime env file, nginx per domain, and whether the app's port answers locally. Every failed check comes with the exact fix command and who can run it (`mcp-callable`, `cli`, or `operator, root shell`). Exits non-zero when a blocking check is missing, so scripts and agents can gate on it. Also available as the read-only `fleet_onboard` MCP tool, and both `fleet add` and `fleet_register` append the unresolved items to their output. **`fleet service install <app> [--force]`** scaffolds the systemd unit for a registered app from its trusted registry fields (working directory, compose file, database dependency) — the path for apps registered under a custom name or compose file, which `fleet add` never covers. Template-only generation, refuses to overwrite an existing unit without `--force`. Also available as the `fleet_service_install` MCP tool. `fleet deploy` runs the blocking subset as a preflight before the build (unit exists; compose-required env vars have a vault entry and an unsealed runtime env file), so a doomed deploy fails immediately with the fix commands instead of dying mid-build with a bare npm/docker error. Apps whose compose needs nothing deploy exactly as before. ## Deployment Flow ```mermaid graph TD Deploy["fleet deploy app|dir"] Deploy --> Register{"Already\nregistered?"} Register -->|No| Add["Register app"] Register -->|Yes| Build Add --> Build["docker compose build"] Build --> Start{"Service\nrunning?"} Start -->|No| StartSvc["systemctl start"] Start -->|Yes| Restart["systemctl restart"] StartSvc --> Healthy["App deployed"] Restart --> Healthy ``` ## Boot Refresh On every systemd start — including reboots — Fleet pulls the latest code from GitHub and rebuilds the image if needed, before starting the container. The flow is entirely fail-safe: any failure at any step (dirty working tree, no remote, fetch error, non-fast-forward merge, build failure, or a 900-second wall-clock timeout) is logged and falls through to a plain `docker compose up` with the existing image. The container will always start. **New commands** | Command | Description | |---------|-------------| | `fleet boot-start <app>` | Entry point systemd now invokes (`ExecStart`). Runs refresh then `docker compose up`. Not typically run by hand. | | `fleet rollback <app>` | Re-tags `<image>:fleet-previous` → `<image>:latest` and restarts the service. Fleet tags the previous image automatically before every build. | | `fleet patch-systemd` | Brings every installed unit up to the current template: `ExecStart=fleet boot-start`, `TimeoutStartSec=900`, the start rate limit moved into `[Unit]`, the `ExecStartPre` compose-down teardown removed, and the `fleet-unseal` / `docker-databases` dependencies added where they apply. Backs the original up to `<path>.service.bak`, write-once. | | `fleet patch-systemd --rollback` | Restores all `.bak` unit files and runs `daemon-reload`. | **Kill switch** To disable boot refresh entirely — next `systemctl start` goes straight to `docker compose up`: ```bash sudo touch /etc/fleet/no-auto-refresh ``` Remove the file to re-enable. **Registry field: `lastBuiltCommit`** Each app in the registry stores the Git commit that was last built. Fleet sets this on `fleet deploy` and on every successful boot-refresh build. Boot refresh skips `docker compose build` when HEAD already matches this value, keeping boots fast when no code has changed. **First boot after upgrade** Any app with `lastBuiltCommit` unset will trigger a full rebuild the first time it boots after upgrading to this version. Expect a longer first boot for those apps. **Recovery escape hatches** | Situation | Action | |-----------|--------| | One app misbehaving after a build | `fleet rollback <app>` | | Registry corrupted | Auto-loads `.bak` on next read | | Broad issue with boot-start behaviour | `sudo touch /etc/fleet/no-auto-refresh` | | Worst case — revert all unit files | `fleet patch-systemd --rollback` | ## MCP Server Fleet exposes 50+ tools via the [Model Context Protocol](https://modelcontextprotocol.io/) for AI-assisted server management — the static surface (server.ts + git / secrets / deps / audit / testflight tool families) plus every migrated registry command exposed through the registry bridge. Run `fleet mcp` to start the stdio server, or install it into Claude Code: ```bash sudo fleet install-mcp ``` Tools cover the full surface area: app lifecycle, secrets, nginx, Git, health checks, and dependency monitoring. See the [MCP documentation](https://fleet.hesketh.pro/mcp/) for the complete tool list. ### Privilege-separated root daemon `fleet mcp` (stdio) runs in-process as whoever launched it, so privileged tools fail when that user is not root — and most fleet operators run their MCP client (e.g. Claude Code) as an ordinary user, not root. `fleet mcp install` sets up a privilege-separated alternative so an unprivileged client can drive the full toolset securely: - a **root daemon** (`fleet-mcp.service`) does all privileged work and is the only process that touches systemd / docker / nginx / the vault; - it listens on a unix socket (`/run/fleet-mcp/mcp.sock`) locked to `root:fleet-guard 0660`, so only root and members of the `fleet-guard` group can connect — the kernel is the access boundary; - the client runs `fleet mcp connect` as the ordinary user; it holds no privilege of its own and just shuttles bytes to the socket; - every tool call passes a **guard**: tier-based authorisation (`read`/`mutate`/`destructive`), per-tier rate limiting, and an append-only audit log at `/var/log/fleet-mcp/audit.log` with secret values redacted; - **destructive tools (deploy, start/stop/restart, rotate-key, git push/release) are denied by default** — opt in per tool in `/etc/fleet/mcp-policy.json`. ```bash # on the server (one command; idempotent) sudo fleet mcp install --write-client-config # sets up the daemon + patches ~/.claude.json # then log out/in so your shell picks up the fleet-guard group, and: fleet mcp doctor ``` Migration is non-breaking: bare `fleet mcp` keeps working exactly as before, so nothing changes until you opt in. To point an MCP client at the daemon manually, use: ```json { "mcpServers": { "fleet": { "command": "fleet", "args": ["mcp", "connect"] } } }</article></body></html>

Fleet

Installation