Run a headless engine

A headless engine runs Admiral's engine on a machine with no window: a VPS, a home server, a build box. It hosts projects like any desktop. You drive it from your other devices.

When to use it

• The work must continue when your laptop closes or leaves home.
• The project needs to live on a specific machine: more memory, a deploy target, a database.
• Several people steer work that runs on one machine.

Start headless

Run the engine without a window:

admiral headless

Run it as a service

For an always-on machine, install the engine as a user service. It starts at login and restarts on failure:

admiral daemon install
admiral daemon start
admiral daemon status

The daemon subcommands are install, start, stop, restart, status, and uninstall. On macOS the service uses launchd; on Linux it uses systemd user units.

Sign in on a headless machine

Sign in from a terminal with an interactive prompt:

admiral login

Two rules:

1. Sign in or sign out only while the engine is stopped.
2. A headless engine started by a service manager has no terminal for sign-in. Run admiral login first; the service picks up the session when it starts.

Use the machine

After it runs, the machine behaves like any host:

1. Sign in on your laptop or phone with the same account.
2. Select the headless machine in the device switcher.
3. Add a project folder on it, and start sessions. The machine runs the agents; you steer from anywhere.

Keep it current

Update the CLI with:

admiral update

Next steps

• Connect another device: the client side of this setup.
• Command line: every command and flag.