Installer#

install.sh installs the Astraeus agent on a machine and connects it to a cluster. It is idempotent: run it again to upgrade, to change the configuration, or to move the machine. This page lists everything it accepts and everything it changes. For a walkthrough, see Add a machine.

Synopsis#

$ curl -fsSL https://<console>/api/v1/install.sh | sudo sh -s -- \
    --apiserver <Astraeus address> --token-file <file> [options]

$ curl -fsSL https://<console>/api/v1/install.sh | sudo sh -s -- --uninstall [--purge]

The console serves the script at /api/v1/install.sh. Each release's notes also name it at https://raw.githubusercontent.com/astralyx-cloud/astraeus/<tag>/deploy/install/install.sh.

To read its built-in help without running anything:

$ curl -fsSL https://<console>/api/v1/install.sh -o install.sh
$ sh install.sh --help

Options#

Flag	Default	Description
`--apiserver <url>`	— (required)	The Astraeus address machines connect to, as shown in the console's install command (on Astraeus Cloud, `https://api.astralyx.cloud`). Must be `https://`; only `http://127.` and `http://localhost` are allowed in plain HTTP.
`--token-file <path>`	— (required)	A file holding the join token, or `-` to read it from standard input. Whitespace is stripped. The token is never accepted as an argument: arguments end up in shell history and the process list.
`--name <name>`	The name the machine had before; otherwise the hostname (`/proc/sys/kernel/hostname`); on a Mac, the local host name in lower case	The machine's name in the cluster. It is written down, so the machine keeps it if the hostname changes. Use letters, digits, `-`, `.` and `_` (the console can only remove machines with such names).
`--releases <url>`	`$ASTRAEUS_RELEASES`, else `https://github.com/astralyx-cloud/astraeus/releases`	Where the agent is downloaded from, now and for later updates. The console serves the release that matches your cluster at `https://console.astralyx.cloud/releases`; its install command passes it. Must be `https://` (the agent runs as root).
`--version <v>`	`$ASTRAEUS_VERSION`, else `latest`	The release to install. `latest` downloads from `<releases>/latest/download`, any other value from `<releases>/download/<v>`.
`--agents <list>`	`drives,credentials,data`	The agent's parts to run besides its main one, comma-separated, or `none`. Known: `drives` (drives and their copies), `credentials` (from your secret stores), `data` (data sources), `edge` (endpoints through Envoy, and the inference gateway on `:8800`). The former names `dvagent`, `secretsync`, `catalog` and `ingress` are accepted. Parts not listed are stopped and disabled.
`--node-identity`	auto	Always authenticate with the identity the machine is issued when it joins, never with its token (`ASTRAEUS_NODE_IDENTITY=on`).
`--no-node-identity`	auto	Always authenticate with the machine's token (`off`). By default (`auto`) the machine uses its issued identity when it can, else its token — for example behind a proxy that terminates TLS.
`--org <name>`	empty	The organisation's name, shown when the machine is later moved. The console's command sets it.
`--org-id <id>`	empty	The organisation's id. A rerun with the same cluster, name and `--org-id` is an upgrade; without it, a rerun is treated as a move.
`--move`	ask	Move a machine connected to another organisation or cluster here, without asking.
`--no-move`	ask	Leave such a machine as it is: the installer stops with `nothing changed`.
`--data-dir <path>`	The previous choice; otherwise asked on a terminal; otherwise none	Where drive copies are kept on this machine. An absolute path without `.` or `..` components. Named once, when the machine first connects; change it in the console after that.
`--no-data-dir`	ask	Do not ask; choose later in the console.
`--network <mode>`	auto	`mesh`: each worker gets its own address, machines are joined by WireGuard; fail if WireGuard cannot be set up. `host`: always the host network. Auto: mesh, except on a machine with RDMA or where WireGuard cannot be set up.
`--runtime <runtime>`	The machine's current runtime; otherwise `containerd`	`containerd`: the bundled containerd. `docker`: the machine's Docker Engine (must be installed). Switching removes the old runtime's Astraeus containers; the workers start again under the new one.
`--install-nvidia-driver`	ask	Allow adding a package repository for the NVIDIA driver without asking (needed without a terminal).
`--no-nvidia-driver`	ask	Never install an NVIDIA driver.
`--install-amd-driver`	ask	Allow installing AMD's packaged driver (`amdgpu-dkms`) without asking (Ubuntu 22.04 and 24.04, x86-64).
`--no-amd-driver`	ask	Install nothing for AMD GPUs.
`--uninstall`	—	Take the agent off this machine. See Uninstall.
`--purge`	—	With `--uninstall` only: also delete the data location.
`-h`, `--help`	—	Print the built-in help and exit.

An unknown option stops the installer with unknown option <flag>.

Environment variables#

Variable	Default	Description
`ASTRAEUS_VERSION`	`latest`	As `--version`.
`ASTRAEUS_RELEASES`	`https://github.com/astralyx-cloud/astraeus/releases`	As `--releases`.
`GITHUB_TOKEN`	—	Sent with downloads, for a private GitHub repository.
`ASTRAEUS_AMDGPU_VERSION`	`31.50`	The release of AMD's packaged driver (`repo.radeon.com/amdgpu/<version>`).

sudo drops your environment. Pass variables after it: … | sudo env ASTRAEUS_VERSION=v0.5.0 sh -s -- …, or use the flags.

Exit status#

Status	Meaning
`0`	Installed and running. The machine is connected, or has not connected within 30 seconds and keeps trying (the installer says so). Also: uninstalled.
`1`	An error, printed as `install: <reason>`, including a name already registered by another installation (`NODE_NAME_TAKEN`).

Prompts#

The script arrives through a pipe, so the installer asks on /dev/tty. With no terminal (cloud-init, Ansible, CI) it never waits:

Question	Asked when	Without a terminal
Move this machine to `<organisation>`?	The machine is connected to another organisation or cluster.	Stops, unless `--move` or `--no-move`.
Where should this machine keep data?	First install, no `--data-dir`, no `--no-data-dir`.	No data location; choose later in the console.
Add a repository and install the NVIDIA driver?	An NVIDIA GPU without a driver, on Debian, Fedora or the RHEL family, when a repository must be added.	No driver, unless `--install-nvidia-driver`.
Add AMD's repository and install `amdgpu-dkms`?	An AMD GPU the kernel cannot drive, on Ubuntu 22.04 or 24.04.	No driver, unless `--install-amd-driver`.

The data-location question lists local filesystems (not network, overlay or pseudo filesystems), best first: NVMe, SSD, RAID, hard disk, then by free space; the system disk last. Answer a number, a folder, Enter for the first, or s to choose later. A disk mounted at / gives /var/lib/astraeus/data; another mount point <mount>/astraeus.

Upgrade, move and rejoin#

When /etc/astraeus/token and /etc/astraeus/agent.env (or, on a machine installed before October 2026, /etc/astraeus/worker.env) exist, the installer compares the machine's Astraeus address, name and organisation id with the new ones:

Situation	What happens
Same address, name and `--org-id`, and the cluster still accepts the machine's credential	Upgrade. The machine keeps its credential and identity; the new token is not used.
Same address, name and `--org-id`, but the cluster answers `401` (the machine was removed)	Rejoin. It joins as a new machine with the new token and a new identity.
Same address and name, another organisation (or no `--org-id`)	Move, after asking. The old credential proves it is the same machine; the cluster removes the old record and revokes the old credential.
Another address or name	Move, after asking. The old record on the other cluster stays (Down) until someone removes it.

A rerun keeps the name, the runtime and the data location. It rewrites the units, /etc/astraeus/agent.env, /etc/astraeus/containerd.toml and /etc/astraeus/owner, and applies --releases, --agents, --network and --node-identity as given (or their defaults).

What it installs (Linux)#

Files and directories#

Path	Mode	What
`/usr/bin/astraeus-agent`	0755	The machine agent: one binary for all its parts (`astraeus-agent`, `astraeus-agent drives`, `astraeus-agent credentials`, `astraeus-agent data`, `astraeus-agent edge`).
`/usr/bin/astraeus`	0755	A command-line tool installed with the agent. You do not need it: use `astra` from your own computer.
`/usr/bin/astraeus-openshell-driver`	0755	OpenShell's compute driver, when the release has it. Not a service.
`/usr/lib/astraeus/bin/`	0755	containerd, `containerd-shim-runc-v2`, `ctr`, runc, `runsc`, `containerd-shim-runsc-v1`, `nvidia-ctk`, `nvidia-cdi-hook`. Not on the `PATH`.
`/usr/lib/astraeus/cni/`	0755	CNI plugins: `bridge`, `host-local`, `loopback`, `portmap`.
`/usr/lib/astraeus/openshell/`		NVIDIA OpenShell's sandbox, its policy and the pinned supervisor image name, for agent runs.
`/usr/lib/astraeus/agent/anemoi-assistant`	0755	The Assistant harness mounted into agent runs (at `/.astraeus/bin/anemoi-assistant`).
`/usr/lib/astraeus/selinux.sh`	0755	The runtime's SELinux labelling.
`/usr/lib/astraeus/licenses/`, `THIRD_PARTY`, `versions.env`	0644	Licences and pinned versions of the bundled components.
`/lib/systemd/system/astraeus-*.service`	0644	The units (below).
`/etc/systemd/system/astraeus-agent.service.d/10-runtime.conf`	0644	Makes the machine agent require its runtime (`astraeus-containerd.service` or `docker.service`).
`/etc/astraeus/`	0750	Configuration.
`/etc/astraeus/token`	0600	The join token, then the machine's credential.
`/etc/astraeus/previous-token`	0600	Only while moving: the old credential, proof of identity. Removed once used.
`/etc/astraeus/agent.env`	0640	The agent's configuration (below). Rewritten on every run.
`/etc/astraeus/owner`		`ORG`, `ORG_ID`, `APISERVER`: whose the machine is.
`/etc/astraeus/containerd.toml`	0644	The bundled containerd's configuration. Rewritten on every run (with the bundled runtime).
`/var/lib/astraeus/worker/`	0750	The machine agent's state: workers' files, the mesh key, the machine's issued identity (`identity/`), GPU fault records.
`/var/lib/astraeus/containerd/`		Images and containers of the bundled containerd.
`/run/astraeus/containerd/`		containerd's socket and runtime state.
The data location (`--data-dir`)	0755	Created if missing.

The machine agent itself writes /var/run/cdi/nvidia.yaml (with a fingerprint file beside it) and /var/run/cdi/amd-astraeus.json on GPU machines.

`/etc/astraeus/agent.env`#

Variable	Value written
`ASTRAEUS_APISERVER_URL`	`--apiserver`
`ASTRAEUS_NODE_NAME`	The machine's name
`ASTRAEUS_JOIN_TOKEN_FILE`	`/etc/astraeus/token`
`ASTRAEUS_PREVIOUS_TOKEN_FILE`	`/etc/astraeus/previous-token`, only while moving
`ASTRAEUS_NODE_IDENTITY`	`auto`, `on` or `off`
`ASTRAEUS_WORK_ROOT`	`/var/lib/astraeus/worker`
`ASTRAEUS_RUNTIME`	`containerd` or `docker`
`ASTRAEUS_CONTAINERD_SOCKET`	`/run/astraeus/containerd/containerd.sock` (containerd only)
`ASTRAEUS_CNI_DIR`	`/usr/lib/astraeus/cni`
`ASTRAEUS_NVIDIA_TOOLKIT_DIR`	`/usr/lib/astraeus/bin`
`ASTRAEUS_NETWORK_MODE`	`bridge` (mesh) or `host`
`ASTRAEUS_MESH`	`true`, with the mesh only
`ASTRAEUS_DATA_DIR`	`--data-dir`, when chosen
`ASTRAEUS_RELEASES_URL`	`--releases`, where updates come from

To change a setting, edit the file and sudo systemctl restart astraeus-agent (and the parts that run), knowing the next run of the installer rewrites it; for settings that must survive, use a systemd drop-in.

systemd units#

Unit	Runs	Notes
`astraeus-containerd.service`	`/usr/lib/astraeus/bin/containerd --config /etc/astraeus/containerd.toml`	With the bundled runtime. `KillMode=process` and `Delegate=yes`: restarting it leaves workers running. `OOMScoreAdjust=-999`.
`astraeus-agent.service`	`/usr/bin/astraeus-agent`	Always. Runs the machine's work. `KillMode=process`: stopping it leaves workers running.
`astraeus-agent-drives.service`	`/usr/bin/astraeus-agent drives`	Default. Exports and mounts drives (NFS).
`astraeus-agent-credentials.service`	`/usr/bin/astraeus-agent credentials`	Default. Resolves credentials on the machine.
`astraeus-agent-data.service`	`/usr/bin/astraeus-agent data`	Default. Serves data sources.
`astraeus-agent-edge.service`	`/usr/bin/astraeus-agent edge`	With `--agents …,edge`. Needs Envoy, installed separately.

Every agent unit reads EnvironmentFile=/etc/astraeus/agent.env, restarts on exit (Restart=always, RestartSec=5) and has LimitNOFILE=1048576. The units are enabled, so they start at boot.

Packages and repositories#

Installed when missing	From
`iproute2` / `iproute`, `iptables`, `wireguard-tools`	The distribution's repositories (`apt`, `dnf`, `yum`, `zypper`, `pacman`)
`policycoreutils-python-utils` (or `policycoreutils-python`), `container-selinux`	Same, only with SELinux enabled
NVIDIA driver	See GPUs. May add `/etc/apt/sources.list.d/astraeus-nvidia.list` (Debian), RPM Fusion (Fedora), EPEL and NVIDIA's CUDA repository (RHEL family).
`linux-modules-extra-$(uname -r)`, `linux-firmware`	Ubuntu's repositories, for an AMD GPU not driven
`amdgpu-dkms`	AMD's repository, added as `/etc/apt/sources.list.d/astraeus-amdgpu.list` with the key `/etc/apt/keyrings/astraeus-rocm.gpg`

Other changes#

Change	When
SELinux file contexts: `container_runtime_exec_t` for the bundled runtime's binaries, `container_var_lib_t` for `/var/lib/astraeus/containerd`, `container_var_run_t` for `/run/astraeus/containerd`; then `restorecon`	SELinux enabled (enforcing or permissive), bundled runtime
firewalld: zone `astraeus` (target `ACCEPT`) with `astraeus0`, `astraeus-cni0`, `astraeus-cni1`, `astraeus-br`; port `51820/udp`; policy `astraeus-forwarding`	firewalld running
Docker containers labelled `io.astraeus.node` and the Docker network `astraeus` removed	Moving from Docker to the bundled containerd
Astraeus containers in the bundled containerd removed	Moving from the bundled containerd to Docker

macOS#

On a Mac (macOS 13.3 or newer) the installer installs only the machine agent, for Eos models. Options that apply: --apiserver, --token-file, --name, --releases, --version, --node-identity, --no-node-identity, --org, --org-id, --move, --no-move, --data-dir, --no-data-dir, --uninstall, --purge. --runtime, the NVIDIA and AMD options and --agents are ignored with a message; --network mesh is an error.

Path	What
`/usr/local/bin/astraeus-agent`, `/usr/local/bin/astraeus`	The machine agent and the command-line tool installed with it.
`/usr/local/lib/astraeus/engines/llama.cpp/<build>/`	The native llama.cpp server.
`/etc/astraeus/` (`token`, `agent.env`, `owner`)	Configuration; the token is root-only.
`/var/lib/astraeus/worker`	The agent's state.
`/Library/LaunchDaemons/cloud.astralyx.astraeus-agent.plist`	The launchd job (`RunAtLoad`, `KeepAlive`).
`/Library/Logs/Astraeus/agent.log`	The log.

agent.env on a Mac sets ASTRAEUS_RUNTIME=native, ASTRAEUS_ENGINES_DIR=/usr/local/lib/astraeus/engines and ASTRAEUS_NETWORK_MODE=host. A data location under Documents, Desktop, Downloads, iCloud or cloud-storage folders, or /Volumes, is refused. See macOS.

Uninstall#

$ curl -fsSL https://<console>/api/v1/install.sh | sudo sh -s -- --uninstall [--purge]

On Linux it:

Stops and disables astraeus-agent and its parts (and the services of an installation from before October 2026, astraeus-worker and the rest).
Stops and removes the Astraeus containers in the bundled containerd (SIGTERM, 5 seconds, then forced), then stops astraeus-containerd.
Removes the containers labelled io.astraeus.node from Docker, and the Docker network astraeus.
Deletes its iptables rules (nat and filter), the astraeus-* network namespaces, and the interfaces astraeus0, astraeus-cni0, astraeus-cni1, astraeus-br and any other bridge it created.
Unmounts what is mounted under /var/lib/astraeus and /run/astraeus.
Deletes /var/run/cdi/nvidia.yaml (only if the agent wrote it) and /var/run/cdi/amd-astraeus.json.
Removes its SELinux rules, and its firewalld zone, policy and port.
Deletes the units, the drop-in directory, the binaries, /usr/lib/astraeus, /etc/astraeus, /run/astraeus and /var/lib/astraeus, never crossing into another filesystem.

Kept	Unless
The data location (drive copies), even inside `/var/lib/astraeus`	`--purge`
GPU drivers, installed packages, added package repositories	Remove them yourself.
The machine's record in the cluster	Remove it in the console (Remove machine).

On a Mac it stops the agent and the engines it started, and removes the launchd job, the binaries, /usr/local/lib/astraeus, /etc/astraeus, /var/lib/astraeus/worker and /Library/Logs/Astraeus.

Running --uninstall twice, or after a failed install, is harmless.

Machine agent settings#

The machine agent (astraeus-agent) reads these variables (or the equivalent --flags). The installer writes the ones in agent.env; set others in a systemd drop-in.

Variable	Default	Description
`ASTRAEUS_APISERVER_URL`	— (required)	The Astraeus address (as `--apiserver`).
`ASTRAEUS_JOIN_TOKEN_FILE`	—	File with the token.
`ASTRAEUS_JOIN_TOKEN`	empty	The token itself. Prefer the file.
`ASTRAEUS_PREVIOUS_TOKEN_FILE`	—	The old credential, while moving.
`ASTRAEUS_NODE_NAME`	The hostname	The machine's name.
`ASTRAEUS_NODE_IP`	The source address of the route to the Astraeus address	The machine's address as other machines reach it (mesh endpoint, host-network work).
`ASTRAEUS_WORK_ROOT`	`/var/lib/astraeus/worker`	The agent's state directory.
`ASTRAEUS_DATA_DIR`	none	Data location, named at first registration only.
`ASTRAEUS_RUNTIME`	`docker` on Linux (the installer writes `containerd`); `native` on macOS	`containerd`, `docker`, `sim` (simulated machine); `native` on macOS.
`ASTRAEUS_CONTAINERD_SOCKET`	`/run/astraeus/containerd/containerd.sock`	containerd's socket.
`ASTRAEUS_CONTAINERD_ROOT`	`/var/lib/astraeus/containerd`	containerd's root, where disk pressure on images is measured.
`ASTRAEUS_CONTAINERD_SNAPSHOTTER`	overlayfs where it works, else `native`	containerd's snapshotter.
`ASTRAEUS_CNI_DIR`	`/usr/lib/astraeus/cni`	CNI plugins.
`ASTRAEUS_RUNC_BINARY`	The bundled runc, else `runc` on the `PATH`	runc for containers.
`ASTRAEUS_RUNSC_BINARY`	The bundled `runsc`	gVisor, for `isolation: sandbox`.
`ASTRAEUS_OPENSHELL_DIR`	The bundled one	NVIDIA OpenShell, for agent runs in a sandbox.
`ASTRAEUS_HARNESS_PATH`	`/usr/lib/astraeus/agent/anemoi-assistant`	The Assistant harness. Without it, the machine takes no runs that ask for it.
`ASTRAEUS_NVIDIA_TOOLKIT_DIR`	`/usr/lib/astraeus/bin`	Where `nvidia-ctk` and `nvidia-cdi-hook` are.
`ASTRAEUS_GPU_MODE`	`nvidia`	How NVIDIA GPUs reach containers: `nvidia` (by id), `cdi` (CDI by id), `cdi-all` (`nvidia.com/gpu=all`, for hosts such as WSL that expose only that). With containerd, `nvidia` means CDI by id.
`ASTRAEUS_DOCKER_SOCKET`	`/var/run/docker.sock`	Docker's socket, with `docker`.
`ASTRAEUS_NETWORK_MODE`	`host` (the installer writes `bridge` with the mesh)	`host` or `bridge`.
`ASTRAEUS_MESH`	`false`	Join the WireGuard mesh.
`ASTRAEUS_DNS_BIND`	The node network's gateway, port 53, with the mesh	Where the machine's DNS listens.
`ASTRAEUS_NODE_PORT_ADDRESS`	empty (every interface)	The address node ports are published on. Set it on a machine that also runs the agent's edge part.
`ASTRAEUS_STOP_GRACE`	`30s`	Grace between stopping a worker and killing it.
`ASTRAEUS_NODE_IDENTITY`	`auto`	`auto`, `on` or `off` (see `--node-identity`).
`ASTRAEUS_APISERVER_CA`	The system's roots	A CA (PEM) to verify the Astraeus address with, instead of the system's roots (for example behind a TLS-inspecting proxy).
`ASTRAEUS_RELEASES_URL`	—	Where updates are downloaded from.
`ASTRAEUS_ENGINES_DIR`	`/usr/local/lib/astraeus/engines`	Native engines (macOS).
`ASTRAEUS_LOG_JSON`	`false`	JSON logs.
`RUST_LOG`	`info`	Log level and filters.

The machine agent exits with status 2 on a configuration error (unreadable token file, invalid data location, no credentials).

Packages#

Each tagged release also publishes .deb and .rpm packages named astraeus-agent (they replace the astraeus-worker packages). They install the same files, enable astraeus-containerd and astraeus-agent, and start containerd, but not the machine agent: put the Astraeus address and name in /etc/astraeus/agent.env, the token in /etc/astraeus/token (mode 0600), then sudo systemctl start astraeus-agent. Enable the parts yourself (sudo systemctl enable --now astraeus-agent-drives astraeus-agent-credentials astraeus-agent-data). Upgrading from an astraeus-worker package keeps its configuration: worker.env is carried over to agent.env. The installer is the supported way; the packages do not install drivers, configure firewalld or choose the network.