fleet-status

fleet-man

A CLI/TUI tool for managing fleets of agents each inside there own isolated devcontainers. This tool enables hugly parallel development, especially if you utilize the fleet-admiral skill (auto added to your claude code on install).

---

What problem does fleet solve?

I made this tool to solve my own problem, and hopefully yours as well. I wanted a tool that allowed the following.

1. Running unlimited parallel agents that don't step on each other. I mean

this in a way beyond the git worktree I don't want ports to step on each other, I don't want one agent deleting the whole computer to step on another agent. I want full isolation.

1. Use my claude code (or any agent you want) subscription at the subscription

price! Many similar tools exist to this, but require you to pay API rates. This tool just uses terminals so you will never need to pay API rates.

1. Not need to constantly setup new environments for agents. Environments need

automated setup.

1. Give me a one screen dashboard to manage all my agents, including knowing

when they need attention.

fleet solves all these problems. I use it every day. A few other senior developers at my company use it every day. You should use it every day!

Contents

• Install
• Usage
• TUI Keybindings
• MCP Server
• Remote MCP — expose MCP & gRPC to remote agents via a fleet gateway
• Microphone — talk to the agents in your instances (voice input in a container)
• Audio output — hear instance audio on a connected client
• Themes — color themes for the TUI (Gruvbox, Catppuccin, Tokyo Night, Solarized)
• Claude Code status mod — which instance you're in and the agents at work, above the Claude Code prompt
• Your SSH agent on a remote fleet — your keys go with you to remote fleets, like ssh -A
• Environment Variables
• Requirements
• Development
• Windows / WSL Setup
• Devcontainer Customizations
• Fleet Launch (in-instance TUI)
• Devcontainer BuildKit
• Devcontainer UID Rewrite

Deep-dive docs (in doc/):

• The Fleet Gateway — how the reverse tunnel relays both MCP and gRPC to your daemon

Install

sudo curl -sL https://raw.githubusercontent.com/BenjaminBenetti/fleet-man/main/install.sh | sh

To install a specific version:

sudo curl -sL https://raw.githubusercontent.com/BenjaminBenetti/fleet-man/main/install.sh | sh -s -- --version v0.2.0

Usage

Run fleet with no arguments to launch the interactive TUI, or use subcommands directly:

# Launch TUI
fleet

# Spawn instances from the current repo
fleet up agent-1
fleet up agent-2

# Stop and restart an existing instance without removing it
fleet stop agent-1
fleet start agent-1

# List instances
fleet ls

# Exec into an instance
fleet exec agent-1 bash

# Open VS Code on an instance
fleet code agent-1

# Launch the in-instance link/app grid (run inside an instance)
fleet launch

# View logs
fleet logs agent-1

# Rebuild an instance's container in place (e.g. after editing devcontainer.json)
fleet rebuild agent-1

# Remove an instance
fleet down agent-1

# Remove a fleet and all its instances
fleet destroy my-project

# Spawn from anywhere with explicit repo
fleet up agent-1 --repo git@github.com:org/my-project.git

# Reference an existing fleet from anywhere
fleet up my-project/agent-3

# Fleet a local directory instead of a git remote: file:// marks a TEMPLATE dir
# that is copied (not cloned) into every new instance. A local path has no repo
# name, so the fleet must be named explicitly (the TUI prompts for it).
fleet up scratch/agent-1 --repo file:///home/me/scratch-project

# Configure automation: agents (workers) and triggers (what fires them)
fleet agent create my-project nightly-builder --system-prompt "Build and report"
fleet trigger create my-project nightly --agent nightly-builder --cron "0 0 * * *" --prompt "Run the nightly build"
# A 'bash' trigger polls a command on its cron and fires only when it exits 0
# (stdout becomes the event payload) — for sources without a webhook
fleet trigger create my-project new-issues --type bash --agent triager --cron "*/5 * * * *" \
  --script 'gh issue list --label needs-triage --json number -q ".[].number" | grep -q .' --prompt "Triage the new issues"
fleet agent list my-project
fleet trigger list my-project
fleet trigger logs my-project nightly   # inspect a trigger's recorded firings

# Virtual microphone (enable it under Settings -> Microphone first)
fleet mic devices                       # this machine's capture devices
fleet mic sources                       # every connected client's capture devices (* = the one recorded)
fleet mic attach                        # provide the microphone without a TUI open (records the Settings device; --device overrides)

Agent state and container lifecycle

Enabling a fleet's Claude Code mount shares ~/.claude, ~/.claude.json, and the project's .claude/settings.local.json across its devcontainer instances. Project overrides survive instance deletion and recreation; other project .claude files remain part of each workspace. Rebuild existing instances to apply newly enabled mounts and project settings links.

Enabling a fleet's Codex mount shares ~/.codex and installs Codex in each instance. Creation and rebuilds also configure Codex's default permissions for automatic approval review ("Approve for me"): approval_policy = "on-request", approvals_reviewer = "auto_review", and sandbox_mode = "workspace-write". These three top-level settings are reset on every create/rebuild of any instance in the fleet, including when Codex is already installed in the image. Use a named Codex profile for a different permission mode; other settings and named profiles are preserved. Configuration requires flock (provided by util-linux or BusyBox on Linux). Fleet keeps a .fleet-codex.lock file in the shared Codex home to coordinate provisioning. Auto-review handles eligible approval requests; actions it rejects may still need your input.

Codex's Linux workspace sandbox requires working bubblewrap/user namespaces inside the container. Standard unprivileged Fleet instances may be unable to create these namespaces; this reproduces with Fleet's own integration fixture, so Codex's workspace sandbox may be unavailable even when installation and configuration succeed. If Codex then requests approval to run outside its sandbox, eligible requests go to automatic review instead of the user. See the Codex container sandbox guidance. Fleet configures the approval mode but does not change the container's security options.

Fleet runs the devcontainer's postStartCommand during creation and after each stop/start cycle. Starting an already running instance does not repeat it. Restart hook failures are logged while the container remains running.

TUI Keybindings

Key	Action
j/k	Navigate
space	Expand/collapse fleet
enter/e	Exec into instance
s	Stop/start instance
o	Open instance in new terminal
a	Add instance
n	New fleet
d	Delete instance/fleet
c	Open VS Code
R	Rebuild instance (preserves workspace)
L	View logs (instance logs, or a selected trigger's event logs in the automation view)
→/l, ←/h	Select / deselect the PR-status auto tag
enter (on PR status)	Open the PR in a browser
A	Switch armada (remote fleet)
r	Refresh
q	Quit

MCP Server

The fleet daemon also runs an MCP server over Streamable HTTP, so AI agents (and any MCP client) can drive fleet programmatically. It starts automatically with the daemon — no extra command.

• It binds 127.0.0.1:6012, or the next free port if 6012 is taken.
• The active port is written to ~/.fleet/mcp.port, so clients can discover the endpoint. The URL is http://127.0.0.1:<port>.
• Requests must carry Authorization: Bearer <token>, where the token is read from ~/.fleet/mcp.token. The loopback port is reachable by any local user, so the token (file mode 0600, same-user only) is the access boundary — matching the daemon's unix socket. The token is generated once and reused across restarts.

Claude Code needs no setup: launching the fleet TUI registers the server in ~/.claude.json as the user-scope fleet entry (URL and token included) and re-syncs it on every launch, so a daemon restart that lands on a new port heals itself. It also installs the Fleet Admiral skill (~/.claude/skills/fleet-admiral), which teaches the agent how to drive these tools. (Local daemons only: when FLEET_GATEWAY/FLEET_SERVER point the TUI at a remote daemon, registration is skipped — point Claude Code at the Public MCP URL from the settings page instead, see Remote MCP. Registration is best-effort and never blocks startup.) The snippet below is for other MCP clients or manual setups.

For convenience the server also writes ~/.fleet/mcp.env (mode 0600) with the endpoint as shell exports, and wires ~/.bashrc to source it, so new shells get:

FLEET_MCP_PORT=6012
FLEET_MCP_URL=http://127.0.0.1:6012
FLEET_MCP_TOKEN=<token>

An MCP client config (mcp.json) can then reference them directly:

{
  "mcpServers": {
    "fleet": {
      "type": "http",
      "url": "${FLEET_MCP_URL}",
      "headers": { "Authorization": "Bearer ${FLEET_MCP_TOKEN}" }
    }
  }
}

(zsh users: add [ -f "$HOME/.fleet/mcp.env" ] && . "$HOME/.fleet/mcp.env" to ~/.zshrc.)

Tools mirror the non-interactive CLI: fleet_list, fleet_status, fleet_version, fleet_logs, fleet_up, fleet_start, fleet_stop, fleet_down, fleet_destroy_fleet, fleet_clone, fleet_rebuild, fleet_exec, the tmux session tools fleet_session_spawn / fleet_session_exec / fleet_session_read / fleet_session_list, and the automation CRUD tools fleet_automation_list, fleet_agent_create / fleet_agent_update / fleet_agent_delete, fleet_trigger_create / fleet_trigger_update / fleet_trigger_delete, and fleet_trigger_logs (mirroring the fleet agent and fleet trigger CLI commands). Interactive, open-ended commands (fleet shell, log following) are intentionally not exposed.

Fleet MCP inside instances

A fleet can also provide these tools to the coding agents running inside its instances, so an agent there can take on work too big for one agent — spin up more instances, run agents in them, collect what they produce — or act as a coordinator for all of your fleets. Turn on Fleet MCP in the fleet's options (e on the fleet). Off by default; it applies to every instance of that fleet, however it was created (by you, a clone, or an automation trigger).

• It is the full fleet MCP, on purpose — every tool, every fleet. That includes tools that reach the host: a bash automation trigger runs its script on the host as you, and a file:// fleet copies host directories into an instance. Turning it on gives anything running in those instances — an agent, a prompt injection of it, the repo's own scripts — host-level access: an agent-escape risk you accept by turning it on.
• The daemon serves MCP on a socket in each instance's control directory (/fleet-mounts/control/mcp.sock); the staged fleet mcp-bridge relays it to an agent over stdio. No token enters the instance: only instances of a fleet with the setting on get the socket, and only that instance's own processes can connect.
• Agents pick it up from their shell, not from their config: ~/.fleet/fleet.rc (sourced by ~/.bashrc) sees the socket and runs fleet mcp-env, which writes a Claude Code plugin (the MCP server plus the Fleet Admiral skill) under ~/.cache/fleet/mcp and exports CLAUDE_CODE_PLUGIN_DIRS. Nothing is written to ~/.claude or ~/.claude.json. So it reaches a claude started from a bash shell opened after the setting was turned on (a new session, an automation agent); a command that clears the environment (sudo without -E, env -i) loses it. Claude Code is the only agent supported so far.
• Devcontainer instances on Linux hosts only. Instances an agent creates are not cleaned up for it — it is told to fleet_down them when done.

Remote MCP

By default the MCP server is loopback-only. To let a remote agent drive your fleet, you can expose it through a fleet gateway — a small public relay you (or someone) runs. Your daemon dials out to the gateway (so it works behind NAT/firewalls) and the gateway routes inbound MCP requests back down that tunnel:

agent ──HTTPS──▶ fleet gateway ──reverse tunnel──▶ your fleetd ──▶ local MCP server

⚠️ Exposing fleet over the internet: the bearer token is the only thing gating access (and over gRPC it grants full daemon control), and the gateway operator can see your traffic — use a gateway you trust and keep the token secret. See The Fleet Gateway for the trust model.

Enable it (in the TUI)

In Settings → Fleet Remote (MCP):

1. Set Gateway URL to the gateway's gRPC endpoint, e.g. https://gateway.example.com:50051 (this is where the daemon registers and dials out — the gateway's --grpc-addr, default port 50051; behind a proxy it's whatever host:port routes to that listener). It is not the public address agents use.
2. Flip Enable Remote MCP on.

Once connected, the read-only Public MCP URL appears (e.g. https://gateway.example.com/mcp/<id>) — that is the address external tools use. The line shows the live connection state (connecting / connected / error).

A second, independent toggle — Enable Remote Fleet — exposes the daemon's gRPC control surface so a remote fleet binary can drive this instance (see Remote control). Turning it on reveals a Remote Fleet via selector with two transports:

• Gateway (the default) — through the same gateway tunnel. With it, a read-only Public GRPC URL appears under the Public MCP URL (computed by the gateway from its --public-grpc-url flag) — that value is what you feed another fleet as FLEET_GATEWAY. With the toggle off, fleetd never negotiates the gRPC tunnel feature, so the gateway rejects any incoming gRPC commands aimed at the daemon.
• SSH — no gateway at all. The daemon serves the same token-gated gRPC server on a loopback port (shown on an SSH Listener row, and recorded in ~/.fleet/ssh.port), and a remote machine reaches it over a plain SSH tunnel that its fleet daemon maintains — see Remote control over SSH. Nothing is exposed beyond what ssh user@host already grants.

The toggles are independent: expose MCP, remote control, or both. Only remote fleet has the SSH transport; MCP and webhooks stay gateway-only.

A third, independent toggle — Enable Webhook — exposes this daemon's automation webhook endpoint through the same gateway. With it on, a read-only Public Webhook URL base appears (e.g. https://gateway.example.com/webhook/<id>), served on the gateway's public HTTP listener — no extra gateway flag needed. A remote system (CI, a SaaS webhook, curl) POSTs an event to <public-webhook-url>/<name>, where <name> is a webhook trigger you defined; the gateway relays it down the tunnel and fleetd fires that trigger's agents if the event passes the trigger's filter (a regex over the body, or a JSON path/value match). The trigger's create/edit dialog renders its full URL ready to paste into the remote system. With the toggle off, fleetd never negotiates the webhook feature, so the gateway 404s the route for this daemon.

Use it from a remote agent

Point the remote MCP client at the Public MCP URL, with the same bearer token your daemon uses (from ~/.fleet/mcp.token):

{
  "mcpServers": {
    "fleet-remote": {
      "type": "http",
      "url": "https://gateway.example.com/mcp/<id>",
      "headers": { "Authorization": "Bearer <token from ~/.fleet/mcp.token>" }
    }
  }
}

Running a gateway

The gateway is the same binary: fleet gateway. TLS is optional: give it a publicly-trusted certificate (e.g. from Let's Encrypt) and it terminates TLS itself, or omit the cert and run it behind a TLS-terminating reverse proxy (see below).

fleet gateway \
  --public-url https://gateway.example.com \
  --tls-cert /etc/fleet/tls/fullchain.pem \
  --tls-key  /etc/fleet/tls/privkey.pem

Flag	Default	Purpose
--public-url	(required)	External base URL agents use; session URLs are <public-url>/mcp/<id>. Scheme (https/http) must match how the public endpoint is actually served
--public-grpc-url	(optional)	External base URL of the gRPC endpoint remote fleet clients dial, e.g. https://gateway.example.com:50051. Daemons that enable Remote Fleet are handed <public-grpc-url>/grpc/<id> as their Public GRPC URL (shown in the TUI, used as FLEET_GATEWAY). Unset = no URL is computed
--tls-cert / --tls-key	(optional)	TLS certificate + key (PEM). Provide both to serve HTTPS, or neither for plain HTTP behind a proxy. A lone cert or key is an error
--public-addr	:443	MCP + /healthz listener — HTTP/1.1 (HTTPS when a cert is set, else HTTP)
--grpc-addr	:50051	Native gRPC listener — HTTP/2 (h2c when cert-less, h2 under TLS). Hosts remote fleet control and fleetd registration. Empty disables both
--max-sessions	1024	Cap on concurrent tunnels
--session-key	(random per boot)	Secret key signing the session-resume tokens daemons present on reconnect. Set it (or FLEET_GATEWAY_SESSION_KEY) so daemons keep the same session URL across gateway restarts; left unset, a restart hands every daemon a fresh URL

Every flag is also settable via environment variable — FLEET_GATEWAY_<FLAG> with dashes as underscores (e.g. FLEET_GATEWAY_PUBLIC_URL, FLEET_GATEWAY_MAX_SESSIONS) — which is handy for configuring the Docker image in Kubernetes. A flag given on the command line wins over its environment variable.

Two ports must be reachable: expose --public-addr to MCP agents and --grpc-addr to remote fleet clients and your daemons (they register over it). A GET /healthz on the public listener returns ok.

There is no separate control port. fleetd registers and carries its reverse tunnel over a long-lived gRPC bidi stream on --grpc-addr (HTTP/2), so the whole gateway is plain HTTP/HTTP-2 — no raw TCP.

Behind a TLS-terminating reverse proxy

Both listeners are L7 — there's no raw-TCP port anymore, so a standard HTTP/gRPC ingress fronts the entire gateway:

• --public-addr (MCP, HTTP/1.1) → a Traefik HTTP IngressRoute (TLS-terminating).
• --grpc-addr (gRPC, HTTP/2) → a Traefik gRPC route (h2c backend) — see Traefik's gRPC guide. This one carries both remote fleet control RPCs and fleetd registration (the same long-lived bidi stream).

Run the gateway with no --tls-cert/--tls-key (plain HTTP/h2c) and let the proxy terminate TLS. For example:

# MCP — L7 HTTP, TLS terminated at Traefik:
apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata: { name: fleet-gateway-mcp }
spec:
  entryPoints: [websecure]
  routes:
    - match: Host(`gateway.example.com`) && PathPrefix(`/mcp`)
      services: [{ name: fleet-gateway, port: 80 }]            # gateway --public-addr
  tls: { secretName: gateway-tls }
---
# gRPC (remote control + fleetd registration) — L7 gRPC, h2c to the backend:
apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata: { name: fleet-gateway-grpc }
spec:
  entryPoints: [websecure]
  routes:
    - match: Host(`grpc.gateway.example.com`)
      services: [{ name: fleet-gateway, port: 50051, scheme: h2c }] # gateway --grpc-addr
  tls: { secretName: gateway-tls }

Set --public-url https://gateway.example.com; the daemon's Gateway URL is the gRPC endpoint, e.g. https://grpc.gateway.example.com (or https://gateway.example.com:50051 without a proxy). Clients (and daemons) verify TLS against the system roots at the proxy edge; the proxy speaks plain HTTP/h2c to the cert-less gateway, which can then bind unprivileged ports and needs no cert.

Run it with Docker

Every tagged release also publishes a gateway image to the GitHub Container Registry, so you don't have to build the binary yourself. It's the same fleet gateway, with the flags passed as docker run arguments (or as FLEET_GATEWAY_* environment variables — see the table above):

docker run -d --name fleet-gateway \
  -p 443:443 -p 50051:50051 \
  -v /etc/fleet/tls:/tls:ro \
  ghcr.io/benjaminbenetti/fleet-man/gateway:latest \
  --public-url https://gateway.example.com \
  --tls-cert /tls/fullchain.pem \
  --tls-key  /tls/privkey.pem

Image tags track releases: :latest (newest stable), :X.Y.Z, and :X.Y. Images are multi-arch (linux/amd64 + linux/arm64). To run behind a TLS-terminating proxy, drop the -v .../tls mount and the --tls-cert/--tls-key flags (and a --public-url http://… or proxy-fronted https://…); the container then serves plain HTTP.

Security model

• No gateway authentication. Anyone can open a tunnel; the gateway just routes bytes. Isolation comes from the unguessable 256-bit id in the public URL.
• The bearer token is the real access boundary. The gateway forwards the Authorization header untouched to your loopback MCP server, whose existing token check gates every request. Treat the Public MCP URL as a capability, but the token is the secret — share both only with agents you trust.
• The id in the URL is not the reconnect credential: the daemon holds a separate secret (never placed in the URL), so a URL holder cannot hijack your tunnel.
• Session-resume tokens are bearer reclaim capabilities. Each registration returns a JWT signed with --session-key; the daemon stores it (mode 0600, next to the secret) and presents it on reconnect, which is what keeps the URL stable across gateway restarts. Anyone holding the token can claim that session, so guard the signing key like any other server secret.
• The public connection is TLS when the gateway holds a cert (the daemon verifies it against the system roots), or when a reverse proxy terminates TLS in front of it. Running the gateway itself on plain HTTP is only safe behind such a proxy (or on a trusted private network) — never expose a cert-less gateway directly.

Remote control (gRPC)

The same gateway tunnel can also carry the daemon's gRPC API, so a remote fleet client can drive your daemon directly — list/up/down, watch live status, stream logs, change config, and so on. It rides the same tunnel as remote MCP but has its own toggle: flip Enable Remote Fleet in Settings → Fleet MCP (independent of Enable Remote MCP, so you can expose MCP, remote control, or both). The gateway serves native gRPC on its dedicated --grpc-addr listener (default :50051); the client dials it as an ordinary gR