Skip to content
Docs
Try it

Guide For self-hosters

Self-hosted variants

The steps that differ on your own server.

Aeolus unreleasedSource on GitHub

You run your own fleet, and you are following a page written for the hosted one. Most of its steps work on your server as written: the software is the same. A few do not, because the hosting service did that step for you. This page lists those steps, page by page, each with the step to use instead and a link back to the page you came from.

It assumes your fleet runs as Self-host sets it up, and stays up as Run the server says. It repeats neither.

Which steps differ

flowchart LR
    hosted["A hosted page"] --> differs{"A step in this list?"}
    differs -->|no| asis["Follow it as written"]
    differs -->|yes| instead["Use the step below instead,<br/>then go back to the page"]
On the hosted page The step that differs On your own fleet
Quick start Sign up Self-host creates your fleet
Commission and crew a ship The crew line’s address It carries your PUBLIC_URL
Commission and crew a ship The Owner field It needs a person ship, which your fleet cannot have yet
Commission and crew a ship, The console Your plan’s limits None
Crew from Claude Code, Crew from Codex Reaching the fleet The session must reach your PUBLIC_URL
The console Signing in, the account menu You sign in as argo
The console Squadrons, Trierarchs and Usage They show once you run and connect each part
Troubleshooting When you sign in to the console Self-host’s own sign-in table
Answer your agents, Bridge and the app Bridge, a chat, Slack, push They need the gateway, and a sign-in you cannot run yet
Setting up a computer, The trierarch plugin Join a machine, trusted repositories, a quiet computer You run the trierarch plugin and set them
Squadrons, Run a squadron Switched on for your fleet, a cap on members You run squadrons and set its limits

One setting runs through all of them. The fleet server, squadrons, the trierarch plugin and the gateway each have an INSTALLATION_TOKEN, which only a hosting service sets. Leave it unset on each: then each part serves your fleet with no switch to turn on.

Quick start

The hosted step. Sign up, and the hosting service makes your fleet.

Instead. Follow Self-host: fleet:init creates your fleet and its operator ship, argo, and prints a link that signs you in.

Back to Quick start.

Commission and crew a ship

The crew line’s address

The hosted step. The starting prompt and every crew line carry the hosted fleet’s address, as <fleetUrl>.

Instead. They carry your server’s PUBLIC_URL. A session crews the ship only when it reaches that address, so set it to the address your sessions really use before you commission, as Self-host, step 2 says. Changed it later? Restart the server, then choose Get starting prompt for a crew line with the new address.

The Owner field

The hosted step. Signed in with your own account, you own what you commission and see no Owner field. Signed in as argo, you pick the owner, a person ship.

On your own fleet. You always sign in as argo, so the Owner field is always there, and it is required: a ship argo commissions in the console is owned by the person ship it names, never by argo. A person ship comes from a person’s account, and nobody signs in to your own fleet with an account yet: the account sign-in service is not one you can run, as Self-host the gateway and app says. So the field says No person ship yet, Commission ship stays off, and the console offers no way to commission a person ship.

There is no step to use instead yet. The ships your plugins commission are not held up by it: a computer still joins through the trierarch plugin, as below.

Your plan’s limits

The hosted step. Your plan may limit how many ships your fleet holds and how many messages it sends a day, and the console says when you reach one.

On your own fleet. Aeolus sets no limit of its own, so no dialog refuses for one, and the limit notices never show.

Back to Commission and crew a ship.

Crew from Claude Code or Codex

The hosted step. Install the plugin, paste the crew line, and the session reaches the hosted fleet over the internet.

Instead. The plugin and the crew line are the same. What changes is the address the session must reach: your PUBLIC_URL.

  • A session on the server itself reaches a localhost address, over plain http.
  • A session on another computer needs an address that computer reaches, over https, as Self-host, step 5 sets up.
  • A session in the cloud, such as Claude Code on the web, runs on a computer that is not yours: it reaches your fleet only at an address it can reach, and only when its environment’s network lets it, as Crew from Claude Code says for the hosted fleet.
  • Codex needs its sandbox to reach the network, on your fleet as on the hosted one: Let the sandbox reach the fleet.

A session that gets no answer from the fleet, or a crew line that cannot connect, usually means PUBLIC_URL is an address that session cannot reach: see Self-host, If something does not work.

Back to Crew from Claude Code or Crew from Codex.

The console

Signing in and the account menu

The hosted step. You sign in with your account through the hosting service. The account menu offers Your account, with your plan’s limits, and you may sign in as argo from there.

Instead. You sign in as argo: with the link npx aeolus-core fleet:init or npx aeolus-core sign-in prints, then with the email and password you set under Settings, Sign-in. Self-host, step 6 walks through it. The account menu shows who you are signed in as, the theme and Sign out; with no plan, it offers no Your account.

Squadrons, Trierarchs and Usage

The hosted step. These pages show once the hosting service switched the part on for your fleet.

Instead. You run each part, give the console its address and connect it under Settings, as Self-host, step 7 shows:

Console page Needs
Squadrons squadrons running, the console started with AEOLUS_SQUADRONS_URL, then Connect squadrons
Trierarchs and Usage The trierarch plugin running, the console started with AEOLUS_TRIERARCH_PLUGIN_URL, then Connect trierarch plugin. Usage shows the tokens your sessions used, which the trierarch plugin keeps

Back to The console.

Troubleshooting a console sign-in

The hosted step. The table When you sign in to the console explains what the account sign-in says: an account with no rights, the sign-in service out of reach, not allowed as argo.

Instead. None of those apply: you sign in as argo, with a link or a password. Use Self-host’s own table, If something does not work: a link that expired or was used, sign-in that needs https, a forgotten password.

Back to Troubleshooting.

Answer your agents, and Bridge

The hosted step. A question to your person ship shows in Bridge at the hosted gateway’s address, in a chat signed in to your fleet, in Slack, and wakes you by web push or email. A question to argo lands in the console’s operator inbox.

On your own fleet. The operator inbox works as written: a question to argo lands there, and you answer it in the console. Bridge, a chat, Slack and push are served by the gateway, which runs beside your server with a database of its own, at its own address. Each also needs the person to sign in with an account, which a self-hosted fleet cannot offer yet. Self-host the gateway and app runs the gateway and says what of it works on your own fleet today.

Back to Answer your agents or Bridge and the app.

Set up a computer, and the trierarch plugin

Join a machine

The hosted step. On the Trierarchs page, choose Join a machine, and run the setup line on the computer.

Instead. First run the trierarch plugin and connect it, as Self-host, step 7 shows. Then join as written. The setup line names the plugin’s FLEET_URL, so the trierarch on the computer reports there: set it to an address each computer reaches. Preparing the computer is the same on your own fleet: Self-host, step 8.

Trusted repositories, and when a computer is quiet

The hosted step. The repositories the fleet marks as trusted, which a trierarch clones by itself when a crew request names one, and how quiet a computer may be before it gets no new ships, are set by whoever runs the trierarch plugin.

Instead. That is you, in the plugin’s environment, read at its start:

Setting What it sets
TRUSTED_REPOSITORIES The repositories every trierarch may clone on demand, as JSON of names to git URLs. Unset, a computer offers only the repositories added to it with aeolus-trierarch add
TRIERARCH_SILENT_AFTER_SECONDS How long a computer may go unheard before it gets no new ships. 300 by default: the 5 minutes the hosted pages name

The trierarch plugin README has every setting.

Back to Setting up a computer for your fleet or The trierarch plugin.

Squadrons

Switched on for your fleet

The hosted step. On a hosted installation, squadrons may need to be switched on for your fleet before you connect it.

Instead. There is no switch. Run squadrons with INSTALLATION_TOKEN unset, and it serves your fleet: give the console its address and choose Connect squadrons, as Self-host, step 7 shows.

A cap on squadrons and members

The hosted step. Your installation may cap how many members a squadron has, and Add member is refused beyond it.

Instead. squadrons sets no cap unless you do, in its environment:

Setting Caps
SQUADRONS_PER_FLEET Squadrons in your fleet
SQUADRONS_PER_FORMING_SHIP Squadrons one ship forms
MEMBERS_PER_SQUADRON Members of one squadron

Each is a whole number of at least 1; unset, there is no limit. The squadrons README has every setting.

Back to Squadrons or Run a squadron.

If something does not work

What you see What to do
A crew line cannot reach the fleet PUBLIC_URL is an address that session cannot reach. Set it to the address sessions use, restart the server, and get a new starting prompt.
Commission ship stays off, and Owner says No person ship yet Your fleet has no person ship, and cannot have one yet. See The Owner field.
Squadrons, Trierarchs or Usage is missing from the console The console has no address for that part, or it is not connected. Start the console with its address, then connect it under Settings.
A computer’s setup line points at the wrong address The trierarch plugin’s FLEET_URL is not one that computer reaches. Set it, restart the plugin, and ask for a new setup line on Trierarchs.
A crew request is never placed, naming a repository Add the repository to a computer with aeolus-trierarch add, or name it in the plugin’s TRUSTED_REPOSITORIES.
Nobody can sign in to Bridge, and no chat connects The account sign-in service cannot be run on your own fleet yet. See Self-host the gateway and app.

The code

Aeolus is open source: ThomasHendrickx/aeolus-fleet. The core README and the console README hold every setting of the server and the console.

Next

  • Self-host: the install every step here starts from.
  • Run the server: keep it running, upgrade, back up and restore.