Features

Fleet & Cloud

Deploy your entire project to multiple machines with a single command. Fleet supports two transports (SSH and Cloud) and two deploy modes (muster and push), with sequential or parallel execution. Groups let you orchestrate deploys across multiple projects.

Fleet hierarchy

Fleet organizes machines into a tree structure: fleets contain groups, groups contain machines, and each machine targets a project with its own services.

Loading diagram...

Directory structure

Fleet config is stored as a directory tree at ~/.muster/fleets/. Each machine has its own project.json with connection details.

- - fleet.json
  - skills.json
  - - - project.json

Deploy modes

Each machine uses one of two deploy modes, set when you add it to the fleet.

The remote machine has muster installed. Fleet runs muster deploy remotely via SSH or cloud transport. The remote muster instance reads its own muster.json and executes hooks locally. Requires an auth token for pairing.

bash

# Add a muster-mode machine
muster fleet add prod-1 [email protected] --mode muster --path /opt/myapp

# Auto-pairing happens: tests SSH, checks muster, creates deploy token
# Token stored at ~/.muster/tokens/fleet.json (600 permissions)

Note

If auto-pairing fails, manually pair with muster fleet pair prod-1 --token <token>. Generate a token on the remote with muster auth create fleet-main --scope deploy.

Mode comparison

Name	Type	Description
`muster`	mode	modeRuns muster deploy on remote. Full TUI, health checks, recovery menus, deploy history. Requires muster installed + auth token.
`push`	mode	modePipes hook scripts over SSH. Only requires bash on remote. Best for simple targets and CI runners.

Transports

Each machine uses one of two transport methods. SSH and Cloud machines can coexist in the same fleet.

Direct SSH connection using key-based authentication. Fleet uses BatchMode=yes so SSH must be configured for passwordless access.

SSH options

Name	Type	Description
`ConnectTimeout`	10	10Fail fast on unreachable hosts.
`StrictHostKeyChecking`	accept-new	accept-newAuto-accept new keys, reject changed ones.
`BatchMode`	yes	yesNo interactive prompts.

bash

# Generate a deploy key
ssh-keygen -t ed25519 -f ~/.ssh/deploy-key -N "" -C "muster-fleet"

# Copy to remote
ssh-copy-id -i ~/.ssh/deploy-key [email protected]

# Add with key
muster fleet add prod-1 [email protected] \
  --key ~/.ssh/deploy-key --mode muster --path /opt/myapp

Transport comparison

Name	Type	Description
`ssh`	transport	transportDirect SSH connection. Works on any reachable host. Default transport.
`cloud`	transport	transportWebSocket relay with E2E encryption. For machines behind NATs, firewalls, or different networks. Requires muster-agent on remote.

Quick start

Initialize fleet

bash

muster fleet init

Add machines

bash

muster fleet add prod-1 [email protected] --mode muster --path /opt/myapp
muster fleet add prod-2 [email protected] --mode push

Group machines

bash

muster fleet group web prod-1 prod-2

Deploy

bash

muster fleet deploy              # all machines, sequential
muster fleet deploy web           # deploy to a group
muster fleet deploy --parallel    # all in parallel (max 10)
muster fleet deploy --dry-run     # preview without executing

Machine configuration

Each machine's project.json stores its connection details:

json

{
  "host": "10.0.1.10",
  "user": "deploy",
  "port": 22,
  "identity_file": "~/.ssh/prod-key",
  "project_dir": "/opt/myapp",
  "mode": "muster",
  "transport": "ssh"
}

Machine fields

Name	Type	Description
`host`req	string	stringIP address or hostname.
`user`req	string	stringSSH user.
`port`	number	numberSSH port. Default: `22`
`identity_file`	string	stringPath to SSH private key.
`project_dir`	string	stringProject path on the remote machine.
`mode`	string	stringDeploy mode: `muster` or `push`. Default: `push`
`transport`	string	stringTransport type: `ssh` or `cloud`. Default: `ssh`

Fleet add flags

bash

muster fleet add <name> user@host [flags]

Name	Type	Description
`--mode, -m`	string	stringDeploy mode: `muster` or `push`. Default: `push`
`--port, -p`	number	numberSSH port. Default: `22`
`--path`	string	stringProject directory on the remote machine.
`--key, -k`	string	stringSSH identity file.
`--transport`	string	stringTransport type: `ssh` or `cloud`. Default: `ssh`

Deploy behavior

Deploys one machine at a time. On failure, shows logs and a recovery menu: Retry, Skip, or Abort. Deploy order follows groups in the fleet config.

Deploy flags

Name	Type	Description
`--parallel`	boolean	booleanDeploy to all machines concurrently (max 10 connections).
`--dry-run`	boolean	booleanPreview the deploy plan without executing.
`--json`	boolean	booleanOutput deploy events as NDJSON.
`--sync`	boolean	booleanSync project files to machines before deploying.

Fleet sync

Synchronize project files to fleet machines before deploying. Useful when remotes don't have git access or you want to push local changes directly.

bash

muster fleet sync              # sync to all machines
muster fleet sync prod-1       # sync to one machine
muster fleet deploy --sync     # sync + deploy in one step

Note

Fleet Sync is in beta. It copies hook scripts and project files via SSH/SCP to the remote project_dir.

All fleet commands

bash

muster fleet init                      # create fleet config
muster fleet add <name> user@host      # add a machine
muster fleet remove <name>             # remove a machine
muster fleet group <name> <machines>   # create/update a group
muster fleet ungroup <name>            # remove a group
muster fleet list                      # list machines and groups
muster fleet test [target]             # test SSH connectivity
muster fleet setup                     # interactive fleet setup wizard
muster fleet setup-user <machine>      # create non-root deploy user

Encryption & security

Fleet uses multiple layers of encryption depending on the transport.

SSH transport

Name	Type	Description
`SSH tunnel`	encryption	encryptionAll communication encrypted by SSH. Credentials exported on remote side, never sent as arguments.
`RSA-4096 fleet keys`	encryption	encryptionPer-fleet keypair for encrypted agent reports. AES-256-CBC session keys wrapped with RSA-4096.
`Ed25519 payload signing`	signing	signingPayload signing with RSA-2048 fallback for tamper detection.

Cloud transport

Name	Type	Description
`X25519 key exchange`	encryption	encryptionCurve25519 Diffie-Hellman per session. New keys for each connection.
`NaCl box (XSalsa20-Poly1305)`	encryption	encryptionAuthenticated encryption for all command payloads. 40-byte overhead (24-byte nonce + 16-byte MAC).
`End-to-end`	property	propertyRelay routes encrypted frames but cannot decrypt them. Zero-trust relay model.

Groups — multi-project orchestration

While fleet deploys one project to many machines, groups deploy many projects as one coordinated operation. Use groups for monorepos or multi-service architectures where projects need to deploy together in order.

bash

muster group create production                    # create a group
muster group add production api /opt/api          # add projects
muster group add production frontend /opt/web
muster group deploy production                    # deploy all in order

Fleet vs Groups

Name	Type	Description
`Fleet`	scope	scopeOne project → many machines. Horizontal scaling. Config: ~/.muster/fleets/
`Groups`	scope	scopeMany projects → one coordinated deploy. Monorepo orchestration. Config: ~/.muster/groups.json
`Per-Service Remote`	scope	scopeOne service → one remote host. Configured per-service in muster.json via the remote block.

Tip

Fleet, Groups, and per-service remote are different features that don't conflict. You can use all three in the same project — a service can deploy remotely via SSH, while the full project deploys to a fleet, and multiple projects coordinate via a group.

Cloud protocol details

The Muster Transport Protocol (MTP v1) uses WebSocket binary frames with a fixed 89-byte header followed by a variable-length payload.

text

Offset  Size  Type              Field
------  ----  ----------------  ---------------------------
0       1     uint8             Version      (0x01)
1       1     uint8             MsgType
2       4     uint32 BE         PayloadLength
6       16    [16]byte          RequestID
22      32    [32]byte          SourceID
54      32    [32]byte          DestID
86      1     uint8             Flags
87      2     [2]byte           Reserved
89      N     []byte            Payload

Note

Full protocol specification and source code: github.com/Muster-dev/muster-fleet-cloud

Remote Deploy Skills