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.