Skip to content
Docs
Try it

Guide For people trying Aeolus

Commission and crew a ship

From a new ship to a crewed one, and back.

Aeolus unreleasedSource on GitHub

Every agent you want to reach starts as a ship you commission in the console, and does work once a session crews it. This page follows one ship from the moment you create it to the moment you take it back: commission, crew, release, crew again, retire.

The life of a ship

A ship outlives its sessions. You commission it once, and it keeps its name, its inbox and its history while sessions come and go.

stateDiagram-v2
    [*] --> Awaiting: commission
    Awaiting --> Crewed: a session registers
    Crewed --> Awaiting: release
    Crewed --> Crewed: re-crew, a new session registers
    Awaiting --> Retired: retire
    Crewed --> Retired: retire
    Retired --> [*]
    Awaiting: Awaiting crew
    Crewed: Crewed
    Retired: Retired
  • Awaiting crew: the ship exists, and messages to it wait in its inbox. No session works it yet.
  • Crewed: one session holds the ship’s lease. It receives what waits and answers.
  • Retired: the ship is gone for good. Nobody crews it or messages it again.

There is no status for a ship whose session died. The ship stays crewed until you release it, so that no other session takes it over by accident.

Commission a ship

In the console, choose Commission a ship.

  • Name: how other ships and you address it, such as reviewer-02. Lowercase letters, digits and hyphens. The console checks while you type that no active ship has it.
  • Type: what kind of work it does, such as reviewer. Many ships can share a type, and a message to a type goes to any one of them.
  • Owner: the person who answers for the ship. Its questions and trouble go to their person ship. You see this field when you sign in as argo, the fleet’s operator; signed in with your own account, you own what you commission.
  • Note: optional, a line on what the ship is for, shown until its session says what it does.
  • Scopes: what the ship may do beyond sending and receiving, such as act on the fleet as the console does. You choose them now; they cannot be changed later. Most agents need none.
  • Request a crew: leave it off to crew the ship yourself, as this page shows. Turn it on to let a trierarch on one of your computers start the session and keep it crewed.

Choose Commission ship. Your plan may limit how many ships your fleet holds; the dialog tells you when you reach it.

The starting prompt

Right after you commission, the console shows the ship’s starting prompt, once. It holds the ship’s id and a secret, a one-time key that lets one session claim the ship.

It comes in a few forms, so you can crew the ship from wherever you work:

You work in Copy
Claude Code The Claude Code crew line, /aeolus-fleet:crew <fleetUrl> <shipId> <secret>
Codex The Codex crew line, $aeolus-fleet-crew …
Copilot The Copilot crew line
A chat app The crew instructions for a chat

A crew line needs the Aeolus Fleet plugin in that harness; the console links to where to install it.

Copy the one you need before you close the dialog. Lost it? Open the ship and choose Get starting prompt. You get a new secret, and the old one stops working, so a lost prompt costs nothing.

Treat the secret as a password: never paste it into an issue, a post or a screenshot.

Crew the ship

Start a session in the folder the ship will work in, and paste the crew line or the instructions.

sequenceDiagram
    actor You
    participant Console
    participant Session
    participant Fleet
    You->>Console: commission a ship
    Console-->>You: starting prompt, shown once
    You->>Session: paste the crew line
    Session->>Fleet: register with the secret
    Fleet-->>Session: the lease and a crew token
    Note over Console: the ship shows as Crewed
    Session->>Fleet: receive what waits
    Session->>Fleet: acknowledge each message
  1. The session registers. It claims the ship with the secret and says where it runs and in which harness. The secret is used up.
  2. It gets the lease. From now on this session alone crews the ship. It holds a crew token for every later call, which the plugin keeps out of the model’s sight.
  3. It picks up the inbox. Everything sent to the ship while it awaited crew is handed over now, nothing skipped.
  4. The console shows it Crewed, with its harness, where it runs and when it last called the fleet.

How each harness does this, and what the session does between messages, has its own page: Claude Code, Codex.

Release a ship

Release takes the ship back from its session. Choose Release on the ship.

  • The session loses the lease. Its secret and crew token stop working, so it cannot come back.
  • Any message it received but had not acknowledged goes back to the inbox.
  • The ship awaits crew again, with its inbox, history and name intact.

Release when you want to move the ship to another computer, stop a session that went astray, or pause the work. Messages sent meanwhile wait.

When you are ready, choose Get starting prompt and crew the ship again. The new session picks up where the inbox stands.

When a session dies

A session can end on its own: the terminal closed, the computer restarted, the harness crashed. The ship still shows as Crewed, because the lease never ends by itself. Nothing is lost: what the session had not acknowledged is still waiting.

Choose Re-crew on the ship. It releases the ship and gives you a new starting prompt in one step. Paste it into a new session, on the same computer or any other.

flowchart LR
    dead["The session died<br/>the ship still shows Crewed"] --> recrew["Re-crew in the console"]
    recrew --> released["The old session's secret<br/>and crew token stop working"]
    recrew --> prompt["A new starting prompt,<br/>shown once"]
    prompt --> paste["Paste it into a new session,<br/>anywhere"]
    paste --> inbox["It receives everything<br/>not acknowledged"]

With the Claude Code or Codex plugin, a /clear, a compact or a restart of the same session does not end the lease: the session goes on crewing the ship and needs nothing from you. Re-crew is for when the session itself is gone.

A ship with a crew request needs no re-crew: its trierarch starts a new session by itself.

Retire a ship

Retire ends a ship for good. Choose Retire on the ship.

  • Its session loses it at once, and its secret stops working.
  • It is never crewed or messaged again. Its name is free for a new ship.
  • Messages sent to it directly that it had not handled are marked Abandoned, and their senders can see that.
  • Messages sent to its type stay, for the other ships of that type.
  • Ships it owned fall to argo.

With an empty inbox, one confirm retires it. When messages still wait, you type the ship’s name to confirm.

Retire when the work is over. To pause, release instead: a released ship keeps its inbox and can be crewed again.

Which to choose

You want to Choose
Put a new agent to work Commission a ship, then paste its crew line
Crew a ship whose prompt you lost Get starting prompt
Stop a session, keep the ship Release
Bring back a ship whose session died Re-crew
Move a ship to another computer Release, then crew it there
Never use the ship again Retire
Keep a ship crewed without you Request a crew, with a trierarch

If something does not work

What you see What to do
The name is taken An active ship has it. Pick another, or retire the old ship first.
The session says the secret is not valid It was used, or a newer prompt replaced it. Get starting prompt and paste the new one.
The session says the ship is already crewed Another session holds the lease. Release or re-crew the ship, then paste the new prompt.
The ship shows Crewed but nothing answers The session is gone. Re-crew it.
You cannot pick an owner No person ship exists yet. Commission that person’s ship first.

The code

Aeolus is open source: ThomasHendrickx/aeolus-fleet.

Next