Docs/Tutorials/The fleet map
Tutorials

The fleet map

5 min read

Once more than one agent is running, the question stops being "what is this session doing" and becomes "is anything waiting on me". The fleet map answers that in one picture: every machine, every agent, and who needs you - across your whole fleet rather than one window.

This takes about five minutes. You need at least one session running; the map is more useful the more you have, but it reads the same either way.

  1. Open the fleet map

    In the Cockpit, choose Fleet Map in the left rail. The line along the top is the whole answer before you look at anything else: how many sessions exist, how many machines they are spread over, how many repositories they touch, and - in red - how many are waiting on you.

    If that last number is zero, you can close the tab. That is the point of the page.

  2. Read the shape

    Underneath, the fleet is drawn as a tree. Your Gateway sits at the top, each machine hangs off it, and each session is a card on its machine. A card carries the session number, its name, which coding agent is running it, which repository it is in, and how long it has been waiting.

    The Cockpit fleet map grouped by machine: a Gateway node above one machine named SOREN_NORTH, with three session cards beneath it - Add task filtering in demo-app, Tidy the note formatter in notes-cli, and Check the forecast parser in weather-widget, each marked Needs you
    The Cockpit fleet map grouped by machine: a Gateway node above one machine named SOREN_NORTH, with three session cards beneath it - Add task filtering in demo-app, Tidy the note formatter in notes-cli, and Check the forecast parser in weather-widget, each marked Needs you

    The coloured dot is the state, and the key along the bottom tells you which is which. Red is the one that matters: it means an agent has stopped and is waiting for a human.

  3. Group it a different way

    The buttons above the map re-draw the same fleet around a different question. By machine answers "is one computer overloaded". By repository answers "how many agents are in this codebase at once", which is the one that catches two agents about to collide. By agent answers "what am I actually running".

    Click between two of them now. Nothing changes about your fleet - only how it is arranged in front of you.

  4. Find one session and go to it

    Type part of a name into the search box and the map narrows to matching sessions. Click a card to open that session and answer it. That is the whole loop the map exists for: spot the red one, click it, deal with it, come back.

Note
With a single machine the map looks modest, and that is fine - it is still the fastest way to see everything waiting on you. It earns its keep when you are running several machines, which is when no single window can show you the fleet any more.
Tip
The fleet map is a browser page served by your Gateway, so it is also what you open from a laptop that is not yours. Nothing to install, and the same picture.

Next

For what each grouping does in detail, how the fleet list differs from the map, and what an unreachable machine looks like, see The fleet map in the Cockpit reference. To reach all of this from somewhere other than your desk, see Your whole fleet in a browser tab.