Host Commands

Manage hosts in your Clawrium fleet.

clawctl host <command> [options]

Commands

Command	Description
clawctl host create	Register a new host with the fleet
clawctl host edit	Edit a host's properties (alias, IP address, description)
clawctl host get	List all registered hosts
clawctl host delete	Remove a host from the fleet
clawctl host status	Check status of a host
clawctl host reset	Reset a host, removing all agents and users
clawctl host validate	Validate NemoClaw sandbox health on a host
clawctl host address	Manage multiple addresses for a host

---

clawctl host create

Register a host with the fleet.

clawctl host create <hostname> --user xclm [--alias NAME] [--port PORT]

On first run for a hostname, this command generates a per-host SSH keypair under ~/.config/clawrium/keys/<hostname>/ and tries to verify SSH access as xclm. If that fails (typical on a fresh host where xclm does not yet exist), it prints the Linux and macOS manual setup commands — with your freshly-generated public key embedded inline — and exits non-zero.

Run those commands on the host (see Host Preparation), then re-run clawctl host create to actually register the host.

The --bootstrap flag was removed in #547. It promised automatic xclm setup but required the bootstrap user to already have passwordless sudo, which was the same precondition manual setup ends with.

Arguments

Argument	Description
hostname	Host IP address or hostname

Options

Option	Short	Description
--port	-p	SSH port (default: 22)
--user	-u	Management user on the host (must be xclm)
--alias	-a	Friendly name for this host

Example — first run (xclm not yet set up)

$ clawctl host create 192.168.1.100 --user xclm --alias pi-lab
Generating SSH keypair for '192.168.1.100'...
Keypair created: /home/user/.config/clawrium/keys/192.168.1.100/xclm_ed25519.pub
xclm SSH verification failed: Authentication failed - check SSH keys

Manual setup required. Log into the host with a sudo-capable user and
run the block that matches its OS:

## Linux
sudo useradd -m -s /bin/bash xclm
…

## macOS
sudo dscl . -create /Users/xclm
…
sudo dseditgroup -o edit -a xclm -t user com.apple.access_ssh

Then re-run: clawctl host create 192.168.1.100 --user xclm

Example — re-run (xclm configured)

$ clawctl host create 192.168.1.100 --user xclm --alias pi-lab
host/pi-lab created on 192.168.1.100:22

Host Key Verification

If the host key is unknown, the command surfaces a prompt and exits non-zero. Run ssh -p <port> xclm@<hostname> once to record the key, then re-run clawctl host create.

Exit Codes

Code	Meaning
0	Host registered (or already exists with matching settings)
1	xclm SSH verification failed (manual setup needed), or host already exists with different settings

---

clawctl host edit

Edit a host record in place — update the SSH user, SSH port, alias, IP address, or description.

clawctl host edit <hostname> [options]

The host is identified by its existing name or alias (the positional HOSTNAME argument). At least one option must be provided.

Arguments

Argument	Description
hostname	Existing host name or alias to edit

Options

Option	Short	Description
--user	-u	New SSH user
--port	-p	New SSH port (1–65535)
--alias	-a	New friendly name for this host
--hostname		New IP address or hostname (e.g. after a DHCP lease renewal). key_id is preserved.
--description	-d	Free-form description for the host. Pass "" to clear it.

Example — change SSH user

$ clawctl host edit mybox --user ops

Example — change SSH port

$ clawctl host edit mybox --port 2222

Example — change alias

$ clawctl host edit mybox --alias lab-pi-4

Example — change IP address (DHCP renewal)

$ clawctl host edit mybox --hostname 10.0.0.55

When --hostname is used, hostname and the primary addresses[] entry are updated atomically; the host's key_id (and therefore the SSH key) is preserved so per-agent secrets stored under the host remain valid. Confirm the public key is still present in authorized_keys on the new address.

Example — set description

$ clawctl host edit mybox --description "primary lab box"

Example — change several fields at once

$ clawctl host edit mybox --user ops --port 2222 --alias lab-pi-4 --description "production server"

Exit Codes

Code	Meaning
0	Host updated successfully
1	Host not found or invalid input

---

clawctl host get

List all registered hosts.

clawctl host get

Example

$ clawctl host get
                    Registered Hosts
┏━━━━━━━━━┳━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━━━┓
┃ Alias   ┃ Host            ┃ Architecture ┃ Cores ┃ Memory (GB) ┃ Tags       ┃
┡━━━━━━━━━╇━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━┩
│ pi-lab  │ 192.168.1.100   │ aarch64      │     4 │         4.0 │ production │
│ nuc-01  │ 192.168.1.101   │ x86_64       │     8 │        16.0 │ dev        │
│ -       │ 10.0.0.50       │ x86_64       │     4 │         8.0 │ -          │
└─────────┴─────────────────┴──────────────┴───────┴─────────────┴────────────┘

---

clawctl host delete

Remove a host from the fleet.

clawctl host delete <hostname> [--force]

Prompts for confirmation unless --force is specified. Also deletes the host's SSH keypair.

Arguments

Argument	Description
hostname	Host hostname or alias to remove

Options

Option	Short	Description
--force	-f	Skip confirmation prompt

Example

$ clawctl host delete pi-lab
Remove host 'pi-lab'? This cannot be undone. [y/N]: y
Host 'pi-lab' removed successfully.
Keypair for '192.168.1.100' deleted.

Exit Codes

Code	Meaning
0	Host removed successfully or operation cancelled by user
1	Host not found or removal failed

---

clawctl host status

Check status of a host.

clawctl host status <hostname> [--refresh]

Shows connection status, hardware information, and metadata. Use --refresh to update hardware information.

Arguments

Argument	Description
hostname	Host hostname or alias to check

Options

Option	Short	Description
--refresh	-r	Re-detect hardware capabilities

Example

$ clawctl host status pi-lab
Checking status of 'pi-lab'...
           Host Status: pi-lab
┏━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Property     ┃ Value                       ┃
┡━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ Connection   │ Connected                   │
│ Hostname     │ 192.168.1.100               │
│ Port         │ 22                          │
│ User         │ xclm                        │
│ Added        │ 2026-04-01T10:30:00Z        │
│ Last Seen    │ 2026-04-05T08:15:00Z        │
│ Tags         │ production                  │
│ Architecture │ aarch64                     │
│ CPU Cores    │ 4                           │
│ Memory       │ 4.0 GB                      │
│ GPU          │ None detected               │
└──────────────┴─────────────────────────────┘

Refresh hardware information:

$ clawctl host status pi-lab --refresh
Checking status of 'pi-lab'...
Refreshing hardware information...
Hardware information updated.

Exit Codes

Code	Meaning
0	Host is connected
1	Host not found or disconnected

---

clawctl host reset

Reset a host, removing all agents and users.

clawctl host reset <hostname> [options]

This command will:

• Stop and remove all *claw services
• Remove all users with uid >= 1000 (except xclm)
• Clean clawrium configuration paths

Arguments

Argument	Description
hostname	Host hostname or alias to reset

Options

Option	Short	Description
--yes	-y	Skip confirmation prompt
--dry-run	-n	Show what would be removed without executing
--untrack		Also remove host from Clawrium tracking after reset

Example

Dry run to preview changes:

$ clawctl host reset pi-lab --dry-run
Scanning 'pi-lab' for targets...

Users to remove (2):
  - zc-work
  - oc-home

Services to remove (2):
  - zeroclaw-work.service
  - openclaw-home.service

Paths to clean (1):
  - /home/zc-work/.config/zeroclaw

Dry run - no changes made

Execute reset:

$ clawctl host reset pi-lab --yes
Scanning 'pi-lab' for targets...
Resetting 'pi-lab'...
Reset complete!
  Users removed: 2
  Services removed: 2
  Paths cleaned: 1

Reset and untrack:

$ clawctl host reset pi-lab --yes --untrack
...
Reset complete!
Untracking 'pi-lab'...
Host removed from tracking.

Exit Codes

Code	Meaning
0	Reset completed successfully
1	Host not found, reset failed, or user aborted

---

clawctl host validate

Read-only aggregation of NemoClaw sandbox health for every openclaw agent on the host. Since v26.7.3, every openclaw runs inside a NemoClaw sandbox — this command runs nemoclaw status <sandbox> for each one and reports the collective health.

clawctl host validate <hostname> [options]

Arguments

Argument	Description
hostname	Host hostname or alias to validate

Options

Option	Short	Description
--output	-o	Output format: table (default), json, yaml
--no-headers		Omit the header row (table mode only)

Example

$ clawctl host validate pi-lab
AGENT      SANDBOX        STATUS      DETAIL
opc-work   opc-work-sbx   healthy
opc-lab    opc-lab-sbx    unhealthy   sandbox not running

When the host has no openclaw agents, nothing is probed:

$ clawctl host validate lab2
host 'lab2': no openclaw agents to validate

Status Values

Status	Meaning
healthy	nemoclaw status <sandbox> succeeded
unhealthy	The status probe failed; DETAIL carries the error
legacy	The agent record has no sandbox_name — remove and re-create the agent
error	The probe could not be dispatched at all

Exit Codes

Code	Meaning
0	All sandboxes healthy, or no openclaw agents on the host
1	One or more sandboxes are not healthy

Related:

• OpenClaw — NemoClaw Substrate — Understanding the sandbox runtime
• clawctl agent get — View the RUNTIME column per agent

---

Address Subcommands

Manage multiple network addresses for a single host. Useful when hosts are reachable via different addresses depending on network context (LAN, VPN, Tailscale, etc.).

clawctl host address <command> [options]

Command	Description
clawctl host address add	Add an address to a host
clawctl host address remove	Remove an address from a host
clawctl host address list	List all addresses for a host
clawctl host address set-primary	Set a different address as primary

---

clawctl host address add

Add an address to a host.

clawctl host address add <host> <address> [--label LABEL]

The first address added to a host is automatically the primary. Additional addresses can be used to reach the host from different network contexts.

Arguments

Argument	Description
host	Host hostname or alias
address	Address as IPv4, IPv6, or hostname (e.g., 192.168.1.1, myhost.local)

Options

Option	Short	Description
--label	-l	Label for the address (e.g., lan, vpn, external)

Example

$ clawctl host address add pi-lab 100.64.0.50 --label tailscale
Address '100.64.0.50' (tailscale) added to host 'pi-lab'

Exit Codes

Code	Meaning
0	Address added successfully
1	Host not found or address already exists

---

clawctl host address remove

Remove an address from a host.

clawctl host address remove <host> <address>

Cannot remove the primary address. Use set-primary to switch to a different address first.

Arguments

Argument	Description
host	Host hostname or alias
address	Address to remove

Example

$ clawctl host address remove pi-lab 100.64.0.50
Address '100.64.0.50' removed from host 'pi-lab'

Exit Codes

Code	Meaning
0	Address removed successfully
1	Host not found, address not found, or cannot remove primary

---

clawctl host address list

List all addresses for a host.

clawctl host address list <host>

Shows the primary address (used for all downstream commands) and any secondary addresses for different network contexts.

Arguments

Argument	Description
host	Host hostname or alias

Example

$ clawctl host address list pi-lab
           Addresses for pi-lab
┏━━━━━━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┓
┃ Address         ┃ Primary ┃ Label     ┃ Added            ┃
┡━━━━━━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━┩
│ 192.168.1.100   │ *       │ lan       │ 2026-04-01 10:30 │
│ 100.64.0.50     │         │ tailscale │ 2026-04-05 14:15 │
└─────────────────┴─────────┴───────────┴──────────────────┘

Exit Codes

Code	Meaning
0	Addresses listed successfully
1	Host not found

---

clawctl host address set-primary

Set a different address as the primary for a host.

clawctl host address set-primary <host> <address>

The primary address is used for all downstream commands (agent install, configure, status checks, etc.). Changing the primary updates the host's hostname field.

Arguments

Argument	Description
host	Host hostname or alias
address	Address to make primary

Example

$ clawctl host address set-primary pi-lab 100.64.0.50
Primary address for 'pi-lab' set to '100.64.0.50'

Exit Codes

Code	Meaning
0	Primary address updated successfully
1	Host not found or address not found