Shell API Reference
The Sanctum shell library provides a set of sanctum_* functions for reading instance configuration, querying node topology, and interacting with the Sanctum infrastructure from Bash scripts and LaunchAgent wrappers.
Source the config library at the top of any script:
source ~/.sanctum/lib/config.shFor notification support, also source:
source ~/.sanctum/lib/notify.shConfig Functions
Section titled “Config Functions”sanctum_get
Section titled “sanctum_get”Read any value from the instance config using dot-notation path.
sanctum_get <key_path>| Parameter | Description |
|---|---|
key_path | Dot-delimited path into instance.yaml |
Returns: The value as a string. Empty string if the key does not exist.
# Read a scalar valueport=$(sanctum_get services.gateway.port)echo "$port" # 18789
# Read the instance slugsanctum_get instance.slug # manoir-nepveu
# Read a nested valuesanctum_get network.vm_ip # 10.10.10.10sanctum_enabled
Section titled “sanctum_enabled”Check whether a config path evaluates to true.
sanctum_enabled <key_path>Returns: Exit code 0 if the value is true, non-zero otherwise.
if sanctum_enabled services.gateway.enabled; then echo "Gateway is active"fi
if sanctum_enabled services.signal_bridge.enabled; then echo "Signal bridge is active"else echo "Signal bridge is disabled"fisanctum_expand
Section titled “sanctum_expand”Expand {{PLACEHOLDER}} tokens in a string using values from the instance config. Used primarily by generate-plists.sh for template rendering.
sanctum_expand <template_string>expanded=$(sanctum_expand "User is {{users.mac}} at {{network.lan_ip}}")echo "$expanded" # User is bert at 192.168.1.10sanctum_home
Section titled “sanctum_home”Return the Sanctum home directory.
sanctum_homeReturns: The path to ~/.sanctum.
config_dir=$(sanctum_home)echo "$config_dir" # /Users/bert/.sanctumsanctum_slug
Section titled “sanctum_slug”Return the instance slug.
sanctum_slugsanctum_slug # manoir-nepveusanctum_name
Section titled “sanctum_name”Return the human-readable instance name.
sanctum_namesanctum_name # Manoir NepveuNetwork Functions
Section titled “Network Functions”sanctum_vm_ip
Section titled “sanctum_vm_ip”Return the VM IP address.
sanctum_vm_ipsanctum_vm_ip # 10.10.10.10sanctum_mac_ip
Section titled “sanctum_mac_ip”Return the Mac bridge IP (the Mac-side IP on the host-only network).
sanctum_mac_ipsanctum_mac_ip # 10.10.10.1sanctum_vm_ssh
Section titled “sanctum_vm_ssh”Return the SSH alias for connecting to the VM.
sanctum_vm_sshssh $(sanctum_vm_ssh) 'uptime'# equivalent to: ssh openclaw 'uptime'sanctum_vm_user
Section titled “sanctum_vm_user”Return the VM username.
sanctum_vm_usersanctum_vm_user # ubuntuIdentity Functions
Section titled “Identity Functions”sanctum_whoami
Section titled “sanctum_whoami”Return the current node identity (read from ~/.sanctum/.node_id).
sanctum_whoamisanctum_whoami # manoirsanctum_is_node
Section titled “sanctum_is_node”Check if the current machine is a specific node.
sanctum_is_node <node_id>Returns: Exit code 0 if the current node matches, non-zero otherwise.
if sanctum_is_node manoir; then echo "Running on the hub"fisanctum_my_type
Section titled “sanctum_my_type”Return the node type of the current machine.
sanctum_my_typesanctum_my_type # hubNode Topology Functions
Section titled “Node Topology Functions”These functions query the nodes section of the instance config. They accept a <node_id> argument (e.g., manoir, chalet).
sanctum_node_type
Section titled “sanctum_node_type”Return the type of a node.
sanctum_node_type <node_id>sanctum_node_type manoir # hubsanctum_node_type chalet # satellitesanctum_node_host
Section titled “sanctum_node_host”Return the LAN hostname or IP of a node.
sanctum_node_host <node_id>sanctum_node_host manoir # 192.168.1.10sanctum_node_host chalet # chalet.localsanctum_node_ts_ip
Section titled “sanctum_node_ts_ip”Return the Tailscale IP of a node.
sanctum_node_ts_ip <node_id>sanctum_node_ts_ip manoir # 100.112.178.25sanctum_node_ts_name
Section titled “sanctum_node_ts_name”Return the Tailscale device name of a node.
sanctum_node_ts_name <node_id>sanctum_node_ts_name manoir # berts-mac-mini-m4-prosanctum_node_user
Section titled “sanctum_node_user”Return the SSH username for a node.
sanctum_node_user <node_id>sanctum_node_user manoir # bertsanctum_node_online
Section titled “sanctum_node_online”Check if a node is reachable (via Tailscale ping or LAN ping).
sanctum_node_online <node_id>Returns: Exit code 0 if the node responds, non-zero otherwise.
if sanctum_node_online chalet; then echo "Chalet is reachable"fisanctum_node_ssh
Section titled “sanctum_node_ssh”SSH to a node over the LAN.
sanctum_node_ssh <node_id> [command...]# Interactive shellsanctum_node_ssh chalet
# Run a remote commandsanctum_node_ssh chalet 'uptime'sanctum_node_ssh_ts
Section titled “sanctum_node_ssh_ts”SSH to a node over Tailscale (for remote/off-LAN access).
sanctum_node_ssh_ts <node_id> [command...]sanctum_node_ssh_ts chalet 'df -h'sanctum_node_vm_ssh
Section titled “sanctum_node_vm_ssh”SSH to the VM on a specific node (if that node has a VM).
sanctum_node_vm_ssh <node_id> [command...]sanctum_node_vm_ssh manoir 'systemctl --user status openclaw-gateway'sanctum_node_enabled
Section titled “sanctum_node_enabled”Check if a specific service is enabled on a node.
sanctum_node_enabled <node_id> <service_name>Returns: Exit code 0 if the service is enabled on that node.
if sanctum_node_enabled chalet home_assistant; then echo "Chalet runs HA"fisanctum_node_service
Section titled “sanctum_node_service”Get a service config value for a specific node.
sanctum_node_service <node_id> <service_name> <key>sanctum_node_service manoir gateway port # 18789sanctum_node_hub
Section titled “sanctum_node_hub”Return the node ID of the hub node.
sanctum_node_hubhub=$(sanctum_node_hub)echo "$hub" # manoirNotification Functions
Section titled “Notification Functions”Source ~/.sanctum/lib/notify.sh for notification support.
sanctum_notify
Section titled “sanctum_notify”Send a notification through configured channels (macOS Notification Center, agent message, etc.).
sanctum_notify <title> <message> [priority]| Parameter | Description |
|---|---|
title | Notification title |
message | Notification body |
priority | Optional: low, normal (default), high |
source ~/.sanctum/lib/notify.sh
sanctum_notify "Backup Complete" "All files backed up successfully"sanctum_notify "Disk Warning" "Boot volume is 90% full" highComplete Script Example
Section titled “Complete Script Example”#!/bin/bashsource ~/.sanctum/lib/config.shsource ~/.sanctum/lib/notify.sh
echo "Instance: $(sanctum_name) [$(sanctum_slug)]"echo "Node: $(sanctum_whoami) ($(sanctum_my_type))"echo "VM: $(sanctum_vm_user)@$(sanctum_vm_ip)"
if sanctum_enabled services.gateway.enabled; then port=$(sanctum_get services.gateway.port) echo "Gateway running on port $port"fi
hub=$(sanctum_node_hub)echo "Hub node: $hub ($(sanctum_node_host $hub))"
if sanctum_node_online chalet; then sanctum_notify "Chalet Status" "Chalet node is online"else sanctum_notify "Chalet Status" "Chalet node is offline" highfi