Manage nodes

Nodes are the compute units in exalsius. Each node represents an individual machine — a cloud VM or a bare-metal server. Import nodes into your node pool so they can be used to deploy clusters.

Node provisioning

exalsius imports nodes via SSH. You can add any machine you have SSH access to, including:

On-premise servers — bare metal or virtualized machines in your own data center.
Cloud instances — virtual machines from any cloud provider (e.g., AWS EC2, Google Compute Engine).

SSH access requirements

You need SSH access to every node you import. We recommend creating a dedicated deploy SSH key per cluster, as all nodes within a cluster must share the same key. The SSH user must have passwordless sudo access for setup and resource discovery.

Prerequisites

Before importing a node, ensure it meets these requirements.

Supported operating systems

OS version	Status
Ubuntu 24.04 LTS	Tested (with latest kernels)
Ubuntu 22.04 LTS	Tested (with latest kernels)

Other Linux distributions may also work, but they have not yet been tested as extensively.

GPU drivers

exalsius automatically installs NVIDIA and AMD GPU drivers for nodes running standard kernels (e.g., Ubuntu's default generic kernel).

Cloud provider custom kernels

Cloud providers often ship custom kernels with suffixes like -aws, -azure, or -gcp. Automatic AMD ROCm driver installation is not supported on these kernels. If your node uses a cloud provider kernel and has AMD GPUs, pre-install ROCm 7.0 before importing. See the AMD ROCm installation guide.

Docker not supported

Nodes cannot have Docker pre-installed. exalsius uses containerd for Kubernetes, and Docker interferes with containerd. Remove Docker before importing the node.

Firewall

SSH (TCP port 22) must be open on all nodes. Additional ports may be required depending on your workload — see firewall configuration.

Import nodes

Nodes can be added through an interactive flow or by providing parameters directly as CLI flags.

InteractiveExplicit

exls nodes import

The CLI prompts for:

Node hostname and endpoint (IP address or DNS name with optional port)
SSH username
Price per hour (enter 0.0 for self-managed nodes)
SSH key — select an existing key or import a new one

After each node, exalsius asks whether you want to add another. This flow is ideal for importing a handful of nodes.

For automated workflows, import a node directly using CLI flags. First, ensure your SSH key is available.

List imported SSH keys:

exls management ssh-keys list

Import a new key if needed:

exls management ssh-keys import --key-path <path-to-private-key-file>

Then import the node:

exls nodes import-ssh \
  --endpoint <ip:port> \
  --username <ssh-username> \
  --ssh-key-id <id-of-imported-ssh-key>

Example:

exls nodes import-ssh \
  --endpoint "203.0.113.42:22" \
  --username "ubuntu" \
  --ssh-key-id "9591093c-17f9-48fa-95bb-11700f330b88"

SSH key management

exalsius stores SSH keys centrally so they can be reused across node imports. Each key has a scope that controls visibility:

Scope	Description
`private`	Only you can see and use this key. This is the default.
`org`	All members of your organization can see and use this key. Use this for shared infrastructure.

Import a key with a specific scope:

exls management ssh-keys import --key-path ~/.ssh/id_rsa --scope org

Without --scope, keys default to private. The interactive flow (exls management ssh-keys import without flags) prompts you to choose between "Private" and "Organization".

List all available keys:

exls management ssh-keys list

Delete a key:

exls management ssh-keys delete <SSH-KEY-ID-or-NAME>

One key per cluster

All nodes within a cluster must share the same SSH key. We recommend creating a dedicated key per cluster and importing it with org scope if multiple team members need access.

Resource discovery

After a successful import, exalsius automatically detects and records available system resources:

GPU devices and their specifications
CPU architecture and core count
Available memory

Verify imported nodes

List all nodes in your pool:

exls nodes list

The output shows each node's hostname, status, GPU summary, price, and import time. IDs are truncated for readability — use nodes get to see full IDs.

Filter and sort

Narrow the list by node type or status, and control the sort order:

exls nodes list --node-type <TYPE> --status <STATUS> --sort-by <FIELD> --order <ORDER>

Option	Short	Values	Description
`--node-type`	`-t`	`cloud`, `self_managed`	Show only nodes of this type
`--status`	`-S`	`discovering`, `available`, `added`, `deployed`, `failed`	Show only nodes with this status
`--sort-by`	`-s`	`created_at`, `hostname`	Sort results by field
`--order`	`-o`	`asc`, `desc`	Sort direction

All options are optional and can be combined. Examples:

# Show only available self-managed nodes
exls nodes list --node-type self_managed --status available

# Sort all nodes by hostname in descending order
exls nodes list --sort-by hostname --order desc

Inspect a node

View full details for a specific node:

exls nodes get <NODE-ID-or-NAME>

The detail view includes hardware resources discovered during import:

GPU — vendor, type, and count (e.g., NVIDIA A100 × 4)
CPU — core count
Memory — total memory in GB
Storage — total storage in GB

If the node has a warning (e.g., a configuration issue detected during discovery), a warning message is displayed.

Node availability

Imported nodes can be assigned to clusters once their status is AVAILABLE.

Delete nodes

Remove one or more nodes from your pool:

exls nodes delete <NODE-ID-or-NAME> [<NODE-ID-or-NAME> ...]

Destructive action

Deleting a node permanently removes it from your node pool.
Any clusters or workloads using the node will lose access to it.
Ensure the node is not hosting active workloads before deleting.

Next steps

Once nodes are imported, use them to deploy clusters.