fleet

KO | EN

gitlite — search

#javascript #python #hacktoberfest #react #ai #typescript #llm #go #golang #android #machine-learning #rust #deep-learning #linux

★ 21 Open GitHub ↗

Docker production management CLI + MCP server for Claude Code

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# fleet

[![audited by auto-audit](https://img.shields.io/badge/audited_by-auto--audit-6366f1?logo=github&logoColor=white)](https://auto-audit.hesketh.pro)

**Docker production management CLI + MCP server**

[![CI](https://github.com/wrxck/fleet/actions/workflows/ci.yml/badge.svg)](https://github.com/wrxck/fleet/actions/workflows/ci.yml)
[![npm](https://img.shields.io/npm/v/@matthesketh/fleet)](https://www.npmjs.com/package/@matthesketh/fleet)
[![Node](https://img.shields.io/node/v/@matthesketh/fleet)](https://nodejs.org)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.6-blue?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
[![License](https://img.shields.io/github/license/wrxck/fleet)](https://raw.githubusercontent.com/wrxck/fleet/main/LICENSE)

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](https://fleet.hesketh.pro) -- [npm](https://www.npmjs.com/package/@matthesketh/fleet) -- [GitHub](https://github.com/wrxck/fleet)

</div>

---

## Table of Contents

- [Architecture](#architecture)
- [Install](#install)
- [Key Features](#key-features)
- [Secrets Flow](#secrets-flow)
  - [Per-app secrets agent (v2, opt-in)](#per-app-secrets-agent-v2-opt-in)
  - [Per-secret rotation (v1.6)](#per-secret-rotation-v16)
  - [Log lifecycle (v1.6)](#log-lifecycle-v16)
  - [Egress observation (v1.6)](#egress-observation-v16)
- [Backups (off-host)](#backups-off-host)
  - [Restore explorer](#restore-explorer)
- [Routines](#routines)
- [Mobile pipelines](#mobile-pipelines)
  - [TestFlight publishing](#testflight-publishing)
  - [App Store compliance audit](#app-store-compliance-audit)
- [Cloudflare guard](#cloudflare-guard)
- [App onboarding](#app-onboarding)
- [Deployment Flow](#deployment-flow)
- [Boot Refresh](#boot-refresh)
- [MCP Server](#mcp-server)
  - [Privilege-separated root daemon](#privilege-separated-root-daemon)
  - [Running fleet from an unprivileged Claude session](#running-fleet-from-an-unprivileged-claude-session)
- [fleet-bot](#fleet-bot)
- [Self-update](#self-update)
- [Testing](#testing)
- [Development](#development)
- [License](#license)

---

## Architecture

```mermaid
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](https://github.com/FiloSottile/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

```bash
npm install -g @matthesketh/fleet
```

Requires Node.js 20+, Docker Compose v2, systemd, nginx, and [age](https://github.com/FiloSottile/age). See the [full setup guide](https://fleet.hesketh.pro/getting-started/) 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 cron and sends alerts on failure.

**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](https://fleet.hesketh.pro/cli/) for the complete command list.

## Secrets Flow

```mermaid
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>.service` runs under `DynamicUser=yes`, loads the per-app key via `LoadCredentialEncrypted`, 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-client`](https://www.npmjs.com/package/@matthesketh/fleet-secrets-client) package 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 rollback` always 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 tail
- `fleet_logs_summary(app, sinceMinutes=60)` — counts + top 10 distinct error messages
- `fleet_logs_search(app, query, sinceMinutes=60, maxResults=20)` — bounded grep
- `fleet_logs_status(app?)` — driver + size per container
- `fleet_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:

```jsonc
{
  "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 <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 `/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@<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 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` | Rewrites `ExecStart` in all installed unit files to use `fleet boot-start`, sets `TimeoutStartSec=900`, and backs up originals to `<path>.service.bak`. |
| `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"] } } }
```

For a hardened setup, run the daemon from a **standalone global install** (`sudo npm i -g @matthesketh/fleet`) rather than a git checkout. `fleet mcp install` and `fleet mcp doctor` warn when the daemon would run from a checkout, because root git activity in that tree can leave root-owned `.git` objects that block the owner's commits; a standalone install has no `.git` to corrupt and can't be rewritten by an unprivileged user.

Same-user caveat: because the client runs as your user, anything else running as that user (in `fleet-guard`) can also reach the socket — the guard limits this to the audited tool surface with destructive actions off by default, but it is not a defence against a full compromise of that account.

### Running fleet from an unprivileged Claude session

Privileged fleet operations (`deploy`, `start`/`stop`/`restart`, `secrets`, `nginx`, `init`, …) need root. An AI agent should run as an ordinary user, so it reaches those one of two ways.

**Recommended — through the daemon (no sudo).** The privilege-separated daemon above runs as root and does the privileged work; the agent connects over the `fleet-guard` socket. Deploy and the lifecycle tools are in the **destructive** tier, which is denied by default, so `fleet_deploy` comes back denied until you opt in per-tool in `/etc/fleet/mcp-policy.json`:

```json
{
  "tiers": { "read": "allow", "mutate": "allow", "destructive": "deny" },
  "tools": {
    "fleet_deploy":  { "apps": ["nutrition"] },
    "fleet_start":   { "apps": ["nutrition"] },
    "fleet_stop":    { "apps": ["nutrition"] },
    "fleet_restart": { "apps": ["nutrition"] }
  }
}
```

Scope each tool to named apps with `{ "apps": [...] }` so the agent can only act on apps you list — a bare `"allow"` permits every registered app and is a much larger blast radius (a prompt-injected agent could redeploy anything). Use `"allow"` only if you genuinely want unrestricted deploys.

Then `sudo systemctl restart fleet-mcp` so the daemon reloads the policy. The other tiers stay untouched and every call is still rate-limited and audited to `/var/log/fleet-mcp/audit.log`. A ready-to-copy file lives at [`data/mcp-policy.example.json`](data/mcp-policy.example.json). This is the path that lets an unprivileged agent deploy without ever touching sudo. **Make sure the agent's MCP client is pointed at the daemon (`fleet mcp connect`), not the in-process stdio server (`fleet mcp`)** — the stdio server runs as the agent's own user and so still hits the root wall below.

**Fallback — the CLI via sudo.** If an agent shells out to the fleet CLI directly (rather than the MCP tools), the CLI hard-requires root and aborts with `requires root privileges`; a non-interactive session can't answer a password prompt. Give its user **passwordless** sudo for the fleet binary:

```sudoers
# /etc/sudoers.d/90-<user>   —  always validate with:  visudo -c
<user> ALL=(ALL) PASSWD: ALL
<user> ALL=(ALL) NOPASSWD: /usr/local/bin/fleet, /usr/local/bin/fleet *
```

> **Order matters.** sudo applies the **last** matching rule. The broad `PASSWD: ALL` must come **before** the specific `NOPASSWD` line — if it comes after, it overrides the NOPASSWD and *every* `fleet` call prompts for a password, silently re-blocking the agent.

This grants passwordless root for the fleet binary only; everything else still prompts. Treat it as you would any root-equivalent capability for that account.

## fleet-bot

A Go companion bot (`bot/`) that provides remote server management through Telegram or iMessage. It runs Claude Code sessions with access to fleet's MCP tools for hands-free operations.

See the [bot documentation](https://fleet.hesketh.pro/bot/setup/) for setup instructions.

## Self-update

When `fleet`'s TUI launches it does a non-blocking `git fetch` against the configured update channel and compares HEAD to that remote branch. If the local repo is behind, a banner appears under the header:

```
↑ Update available: 3 commits ahead — feat: ... Press U to install.
```

Pressing `U` runs `git pull --ff-only origin <channel-branch>` then `npm run build` (refused if the working tree is dirty). The new binary is live for the next `fleet …` invocation. Recheck happens every 30 minutes for long-running TUI sessions.

**Channels**

| channel | tracks | who it's for |
|---|---|---|
| `stable` (default) | `origin/main` — tagged releases only | everyone |
| `prerelease` | `origin/develop` — work in flight, may break | operators willing to canary |

Opt into prerelease for the current process:

```bash
FLEET_UPDATE_CHANNEL=prerelease fleet
```

Or persist it (e.g. in `~/.bashrc` or the systemd unit's `Environment=`):

```bash
export FLEET_UPDATE_CHANNEL=prerelease
```

When the banner is on the prerelease channel it labels itself `↑ Update available (prerelease): …` so you can tell at a glance.

**Escape hatch — track an arbitrary branch**

For forks or release branches, `FLEET_UPDATE_BRANCH=<name>` overrides the channel entirely:

```bash
FLEET_UPDATE_BRANCH=release/2026.q3 fleet
```

## Testing

```bash
npm test                     # unit + mocked tests (~1720 passing)
FLEET_INTEGRATION=1 npm test # also runs boot-refresh + secrets-v2 integration tests
```

Set `FLEET_INTEGRATION=1` to opt into integration tests that hit real systemd / docker. Skipped by default in CI.

## Development

```bash
git clone https://github.com/wrxck/fleet.git
cd fleet
npm install
npm test                 # vitest
npm run build            # compile TypeScript to dist/
npm run dev              # run with tsx (no build needed)
npm run changelog        # regenerate CHANGELOG.md from git tags
```

See [CHANGELOG.md](./CHANGELOG.md) for the release history (auto-generated from tags; the GitHub releases page has extra context). The `npm run changelog` script regenerates it after a tag bump.

## License

MIT

fleet

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README