fleet MCP server
Commit Nov 14, 2026Manages Docker Compose applications with systemd orchestration, Nginx routing, encrypted secrets, and AI-assisted operations via an MCP server.
Also known as wrxck/fleet
- Stars
- 20
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 14, 2026
- License
- MIT
What is fleet MCP?
fleet manages Docker Compose applications with systemd orchestration, Nginx routing, encrypted secrets, and AI-assisted operations via an MCP server.
Summary generated from the project's README
About fleet MCP server
Managing Docker Compose applications on a single server is what fleet enables through a combination of a command-line interface and an MCP server. It provides a centralized way to handle deployment, systemd orchestration, and Nginx routing while maintaining high security through age-encrypted secrets. The system is designed for developers and operators who need to manage production containers with integrated health monitoring, dependency scanning, and automated backups.
Users interact with the system via a CLI, a TUI dashboard, or an AI client using the MCP server. The MCP server operates through a privilege-separated root daemon, allowing an unprivileged Claude session to perform complex operations. It includes specialized tools for log analysis, such as bounded tails and error summaries, which are designed to be token-conservative. The setup requires Node.js 20+, Docker Compose v2, systemd, nginx, and the age encryption tool.
What you can do with it
- 1Analyze application error logsAsk the AI to summarize recent errors or search through container logs for specific issues.
- 2Deploy and manage servicesInstruct the client to build, start, or restart Docker Compose applications by name.
Written from the project's README. Every use case is checked against a quote from it.
Configuration
FLEET_INTEGRATIONFLEET_UPDATE_BRANCHFLEET_UPDATE_CHANNEL
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablewrxck/fleet is public and reachablegithub.com/wrxck/fleet ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-02github.com/wrxck/fleet ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubfleet
Docker production management CLI + MCP server
Manage Docker Compose apps on a single server -- systemd orchestration, nginx routing, age-encrypted secrets, health monitoring, dependency tracking, Git workflows, and an MCP server for AI-assisted operations.
Documentation -- npm -- GitHub
Table of Contents
- Architecture
- Install
- Key Features
- Secrets Flow
- Backups (off-host)
- Routines
- Mobile pipelines
- Cloudflare guard
- App onboarding
- Deployment Flow
- Boot Refresh
- MCP Server
- fleet-bot
- Self-update
- Testing
- Development
- License
Architecture
graph TD
CLI["fleet CLI"]
TUI["TUI Dashboard"]
MCP["MCP Server"]
BOT["fleet-bot (Go)"]
Explorer["Backup Explorer<br/>(browser)"]
CLI --> Core
TUI --> Core
MCP --> Core
BOT -->|"MCP + exec"| Core
Explorer --> BackupCore["Backup core"]
subgraph Core["Core modules"]
Registry["Registry"]
Docker["Docker Compose"]
Systemd["systemd"]
Nginx["nginx"]
Secrets["Secrets vault"]
Agent["Secrets agent v2<br/>(per-app socket)"]
Health["Health checks"]
Git["Git / GitHub"]
Deps["Dependency monitor"]
Routines["Routines<br/>(scheduled tasks)"]
BackupCore
Guard["Cloudflare guard"]
Mobile["Mobile (TestFlight + audit)"]
end
Docker --> Containers["Containers"]
Systemd --> Services["systemd services"]
Nginx --> Proxy["Reverse proxy"]
Secrets --> Vault["vault/*.age"]
Secrets --> Runtime["/run/fleet-secrets"]
Agent --> Containers
Health --> Alerts["Telegram / iMessage"]
BackupCore --> Restic["restic + age<br/>(off-host)"]
Each Docker Compose app is registered with its compose path, domains, port, and container names. Fleet generates systemd units so apps start on boot in the correct order. Secrets are encrypted at rest with age and either decrypted to a tmpfs on boot (v1) or served per-app over a Unix socket by the secrets agent (v2).
Operator-specific identity (GitHub org, home dir, domain, username) lives in data/operator.json — gitignored, instance-local. Copy data/operator.example.json to seed it on a fresh install.
Install
npm install -g @matthesketh/fleet
Requires Node.js 20+, Docker Compose v2, systemd, nginx, and age. See the full setup guide for details.
Key Features
Deploy and manage apps -- fleet deploy <app|dir> builds and starts an app by registered name, or registers a new app from a directory path -- in one command. Control services with start, stop, restart, and logs.
Encrypted secrets -- age-encrypted vault with automatic backups, pre-seal validation, drift detection, and atomic rollback. Decrypted to tmpfs at boot -- secrets never touch disk.
Nginx routing -- Generate proxy, SPA, or Next.js server blocks with fleet nginx add. Automatic config testing and reload.
Health monitoring -- Three-layer checks (systemd + container + HTTP) with fleet health. The watchdog command runs on a timer, restarts an app that is down with a failed unit (at most twice an hour), and alerts when the failure set changes rather than on every run.
Dependency scanning -- Detects outdated packages, CVEs (via OSV), Docker image updates, and runtime EOL across all registered apps.
Git workflows -- Onboard apps to GitHub, manage branches, PRs, and releases from the CLI.
Off-host backups -- fleet backup runs restic against an append-only REST backend with age-encrypted dumps for databases. Includes schedule for systemd-timer-driven recurring backups, verify / integrity for repository checks, and serve for a browser-based restore explorer.
Routines -- fleet routines is a TUI for signal-based scheduled tasks (each routine has a target repo, a trigger condition, and a runner — claude-cli, shell, or mcp). fleet routine-run --id <id> is the headless entrypoint for systemd-timer units.
Mobile pipelines -- fleet testflight dispatches the macOS build workflow and publishes to TestFlight; fleet audit runs an App Store Review Guidelines audit via greenlight.
Cloudflare guard -- fleet guard installs a watchdog layer (cf-snapshot, dns-drift-watch, cert-expiry-watch, cf-audit-monitor) that detects unauthorised dashboard changes and DNS drift on protected zones.
Interactive dashboard -- Run bare fleet to launch a full-screen TUI with real-time status.
Host preflight -- fleet doctor checks every external requirement the rest of the tool assumes (age, docker compose v2, systemd ≥ 240, node ≥ 20), plus the registry, vault, operator config and orphaned-app detection. Run on any fresh server.
Self-update from the CLI -- fleet update [--check] [--channel prerelease] is the non-TUI counterpart to the dashboard banner. Cron-able, ssh-friendly.
Operator config -- fleet config show / get <field> / set <field> <value> and the one-liner fleet whoami keep data/operator.json (username + home + domain + github org) editable from the CLI.
Shell completions -- fleet completions bash | zsh | fish emits a completion script driven from the command registry, so it stays accurate as the migration finishes.
See the CLI reference for the complete command list.
Secrets Flow
graph LR
Import["fleet secrets import"]
Set["fleet secrets set"]
Import --> Encrypt["age encrypt"]
Set --> Encrypt
Encrypt --> Vault["vault/*.age"]
Vault -->|"boot / fleet secrets unseal"| Decrypt["age decrypt"]
Decrypt --> Runtime["/run/fleet-secrets (tmpfs)"]
Runtime -->|"env_file / secrets"| Containers["Docker Containers"]
Runtime -->|"fleet secrets seal"| Encrypt
Vault -.->|"drift detection"| Runtime
Secrets are imported or set individually, encrypted with age, and stored in the vault. On boot (or manually), they are decrypted to a tmpfs mount that Docker containers reference. Sealing writes runtime changes back to the vault. Drift detection compares vault vs runtime to catch unsaved changes.
Per-app secrets agent (v2, opt-in)
The v1 model decrypts every app's secrets to /run/fleet-secrets/<app>/, which means any process on the host can read the tmpfs file. v2 replaces that with a per-app systemd-templated socket service:
- Each app gets its own age keypair; the vault is encrypted to (admin + per-app) recipients.
fleet-secrets-agent@<app>.serviceruns underDynamicUser=yes, loads the per-app key viaLoadCredentialEncrypted, and serves the decrypted env over a Unix socket at/run/fleet-secrets/<app>.sock.- Consumers (the container) fetch secrets via HTTP/1.1 over the socket. The
@matthesketh/fleet-secrets-clientpackage wraps that protocol for Node apps. fleet secrets migrate-v2 <app>orchestrates the move: snapshot, generate per-app keypair, re-encrypt to the new recipient set, edit the compose file + app unit, swap, and auto-rollback on any failure.fleet secrets revert-v2 <app>rolls back from a snapshot if you need to drop back to v1.
Per-secret rotation (v1.6)
Each secret carries metadata (lastRotated, provider, strategy) so fleet knows when it's stale and how to safely rotate it.
fleet secrets ages [<app>] # what's stale, who owns it, when last rotated
fleet secrets ages --motd # MOTD-formatted summary
fleet secrets motd-init # install /etc/update-motd.d/99-fleet-secrets
fleet secrets rotate <app> [<KEY>] # interactive walkthrough, [--dry-run] [--no-restart]
fleet secrets rollback <app> # restore latest snapshot, [--to <ts>]
fleet secrets snapshots <app> # list available snapshots
fleet secrets rotate-key # legacy: rotate the AGE master key
Rotation strategies (auto-detected from secret name, see src/core/secrets-providers.ts):
| Strategy | Examples | Behaviour |
|---|---|---|
immediate |
STRIPE_SECRET_KEY, GITHUB_TOKEN, OPENAI_API_KEY |
Replace value, old dies |
dual-mode |
JWT_SECRET, NEXTAUTH_SECRET, SESSION_SECRET |
New becomes primary, old kept as <NAME>_PREVIOUS so existing user sessions stay valid through grace period (your app must read both for verification) |
at-rest-key |
ENCRYPTION_KEY, FIELD_ENCRYPTION_KEY |
Refused unless --data-migrated passed (you must re-encrypt stored data first) |
user-issued |
USER_API_TOKEN, CUSTOMER_API_KEYS |
Refused — rotate per-user inside your app |
Safety rails on every rotation:
- Pre-rotation snapshot to
vault/.snapshots/<app>-<ts>.env.age(atomic copy+rename) - Hidden input prompt; new value never echoed in full (only
prefix…suffix (N chars)for confirmation) - Format validation against provider regex (catches paste typos)
- Entropy check rejects placeholders (
changeme,password, all-same-char, < 8 chars) - Auto-rollback on any failure during reseal
- Restart + 5s healthcheck gate after re-unseal; manual
fleet rollbackalways available - Append-only audit log at
~/.local/share/fleet/audit.jsonl(mode 0600, never logs values)
Log lifecycle (v1.6)
fleet logs setup <app> # interactive: retention/size/level
fleet logs setup --all # bulk default (7d / 100MB / info)
fleet logs status [<app>] # per-container size, driver, policy applied
fleet logs prune <app> # vacuum journald + truncate runaway json-file logs
fleet logs <app> --since 30m --grep err --level warn # filtered tail
fleet logs setup writes <composePath>/.fleet/logging.override.yml with json-file driver options for rotation. To activate, include the override in your compose start command (or fleet's systemd unit).
MCP tools — all token-conservative with small defaults and truncated flags:
fleet_logs_recent(app, lines=50, level=warn, sinceMinutes=15)— bounded tailfleet_logs_summary(app, sinceMinutes=60)— counts + top 10 distinct error messagesfleet_logs_search(app, query, sinceMinutes=60, maxResults=20)— bounded grepfleet_logs_status(app?)— driver + size per containerfleet_egress_snapshot(app)— outbound destinations + violations
Log redaction
Every log read path redacts secrets and PII before the text reaches you — the CLI (fleet logs, including -f), the TUI log views, and all fleet_logs_* MCP tools. Matches are replaced with [REDACTED:<category>#<fp>], where #<fp> is four hex chars of a per-process salted hash: the same secret appearing twice looks the same within one output, and the fingerprint is meaningless across runs.
Categories, and whether they are on by default:
| Category | Default | What it catches |
|---|---|---|
private_key |
on | -----BEGIN … PRIVATE KEY----- blocks, whole block |
jwt |
on | three base64url segments whose header decodes to JSON with an alg |
aws_key |
on | AKIA/ASIA/ABIA/ACCA + 16 uppercase alnum |
aws_secret |
on | 40-char secret, only next to an aws_*_key name |
provider_token |
on | ghp_/gho_/ghs_/ghu_/github_pat_, xox[baprse]-, sk_live_/rk_live_, AIza, sk-ant-, sk-proj-, sk-, glpat-, npm_ |
auth_header |
on | Authorization: values and bare Bearer/Basic credentials |
uri_credentials |
on | the password in scheme://user:password@host — scheme, user and host are kept |
generic_assignment |
on | the value of a key ending in PASSWORD/SECRET/TOKEN/API_KEY/PRIVATE_KEY/ACCESS_KEY/CLIENT_SECRET/DSN/… — the key name is kept |
iban |
on | mod-97 validated IBANs with a registered country code and length |
credit_card |
on | Luhn-valid numbers with a real card-network prefix |
uk_nino |
on | UK National Insurance numbers, invalid prefixes excluded |
email |
on | email addresses |
phone |
off | phone numbers — digit runs have no checksum to validate against, and logs are full of them (ports, PIDs, byte counts, epochs). Too noisy to enable by default |
ip |
off | public IP addresses — operators need them to debug. When enabled, loopback / RFC1918 / CGNAT / link-local / documentation ranges are still never redacted |
The overriding design rule is no false positives. Commit SHAs, UUIDs, sha256: digests, semver, ISO timestamps, epoch millis, file paths, credential-free URLs, ports, PIDs, byte counts, hex colours, Stripe publishable keys (pk_live_/pk_test_), SSH public keys, image data URIs and bare prose like Invalid password supplied all pass through untouched. There is a regression test for each.
Filter ordering: --grep and --level match the raw line, and redaction is applied to the survivors. Grepping for a hostname, an account id or a customer email therefore still returns the lines you need, instead of silently returning nothing. The caveat that comes with that: because matching happens pre-redaction, grepping for a literal secret value will tell you whether that value appears in the log (you get back a line with a placeholder in it) even though the value itself is never printed. That is an oracle, not a disclosure. Set redaction.enabled: false for the app if you would rather have neither.
Per-app configuration lives under logging.redaction in the registry:
{
"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]+/"]
}
}
}
allowlistwins 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.customPatternsredact 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 andfleet logskeeps working.
Egress observation (v1.6)
fleet egress observe <app> # snapshot current outbound flows via nsenter+ss
fleet egress show <app> # show config + allowlist
fleet egress allow <app> <host> # 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 <app> [--paths …] # tell fleet which paths and dbs to capture
fleet backup register-all # bulk-register every known app
fleet backup snapshot <app> [--tag …] # take an on-demand snapshot
fleet backup snapshot-all # one snapshot per registered app
fleet backup list [<app>] # list snapshots, latest first
fleet backup restore <app> --snap <id> --target <dir>
fleet backup prune # apply retention policy
fleet backup verify # restic check (data integrity)
fleet backup integrity # repository integrity report
fleet backup schedule <app> --cron "..." # install a fleet-backup@<app>.timer unit
fleet backup schedule-all # bulk-install timers from registered apps
fleet backup unschedule <app> # remove the timer
fleet backup status [<app>] # last-snapshot age, sizes, append-only state
fleet backup serve --port <n> # 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
/backupsshowing the latest snapshot per app and any retention lag - a tree explorer at
/backups/explorefor browsing snapshot contents - a per-file streaming endpoint that pipes
restic dumpstraight 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), ormcp-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@<id>.timer — fleet ships the templates and fleet routine-run --id <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 <id> [--target <repo>] [--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 <app> # dispatch the macOS build workflow to TestFlight
fleet testflight builds <app> # list TestFlight builds for the app
fleet testflight update <app> --build <id> --whats-new "..."
fleet testflight delete <app> --build <id> # expire a TestFlight build
fleet testflight doctor <app> # 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 "<title>" --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 approvaldns-drift-watch— detects when DNS records drift from the snapshot (cron, alerts via the same channels asfleet watchdog)cert-expiry-watch— flags certs approaching expiry across all protected hostsfleet-guard/fleet-guard-execute— the orchestrator + executor pair, run as thefleet-guardsystem user with no shell
fleet MCP questions
How do I install fleet?
You can install it globally using npm with the command: npm install -g @matthesketh/fleet.
What are the system requirements for fleet?
Fleet requires Node.js 20 or higher, Docker Compose v2, systemd, nginx, and the age encryption tool.
Can I manage my apps through a dashboard?
Yes, running the bare 'fleet' command launches a full-screen TUI (Terminal User Interface) dashboard with real-time status.
How does fleet handle secrets?
Secrets are encrypted at rest using age and decrypted to a tmpfs mount on boot so they never touch the disk.