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.

Under the hood, these functions read from a JSON cache that was generated from YAML by a Python script. Bash calls jq which reads JSON that was written by Python that parsed YAML that you wrote by hand. The Rube Goldberg machine of config access. But it resolves any key in under 50ms, it never breaks, and it’s been running in production for months. Sometimes the unglamorous solution is the correct one.

Setup

Source the config library at the top of any script:

source ~/.sanctum/lib/config.sh

For notification support, also source:

source ~/.sanctum/lib/notify.sh

Backwards Compatibility

The legacy fos_* prefix aliases (e.g. fos_get, fos_enabled) have been removed. All callers should use the sanctum_* functions directly. If you find a script still using fos_*, it’s overdue for a rename and probably a few other things too.

---

Config Functions

sanctum_get

Read any value from the instance config using dot-notation path. The Swiss Army knife. The one function you’ll use more than all others combined.

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 value
port=$(sanctum_get services.gateway.port)
echo "$port"  # 1977

# Read the instance slug
sanctum_get instance.slug  # manoir-nepveu

# Read a nested value
sanctum_get network.vm_ip  # 10.10.10.10

---

sanctum_enabled

Check whether a config path evaluates to true. Returns an exit code, so it plays nicely with if statements — which is more than can be said for most things in Bash.

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"
fi

---

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.10

Tip

This is the engine behind plist generation. Every {{PLACEHOLDER}} in a template gets resolved through this function. If a placeholder resolves to empty, the template renders with a blank — which is usually a sign that you forgot to fill in instance.yaml.

---

sanctum_home

Return the Sanctum haus directory.

sanctum_home

Returns: The path to ~/.sanctum.

config_dir=$(sanctum_home)
echo "$config_dir"  # /Users/bert/.sanctum

---

sanctum_slug

Return the instance slug.

sanctum_slug

sanctum_slug  # manoir-nepveu

---

sanctum_name

Return the human-readable instance name.

sanctum_name

sanctum_name  # Manoir Nepveu

---

Network Functions

sanctum_vm_ip

Return the VM IP address.

sanctum_vm_ip

sanctum_vm_ip  # 10.10.10.10

---

sanctum_mac_ip

Return the Mac bridge IP (the Mac-side IP on the host-only network).

sanctum_mac_ip

sanctum_mac_ip  # 10.10.10.1

---

sanctum_vm_ssh

Return the SSH alias for connecting to the VM.

sanctum_vm_ssh

ssh $(sanctum_vm_ssh) 'uptime'
# equivalent to: ssh openclaw 'uptime'

---

sanctum_vm_user

Return the VM username.

sanctum_vm_user

sanctum_vm_user  # ubuntu

---

Identity Functions

sanctum_whoami

Return the current node identity (read from ~/.sanctum/.node_id).

sanctum_whoami

sanctum_whoami  # manoir

The existential question, answered in one function call.

---

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"
fi

---

sanctum_my_type

Return the node type of the current machine.

sanctum_my_type

sanctum_my_type  # hub

---

Node Topology Functions

These functions query the nodes section of the instance config. They accept a <node_id> argument (e.g., manoir, chalet). Useful when your haus automation hobby has metastasized into a multi-site distributed system.

sanctum_node_type

Return the type of a node.

sanctum_node_type <node_id>

sanctum_node_type manoir   # hub
sanctum_node_type chalet   # satellite

---

sanctum_node_host

Return the LAN hostname or IP of a node.

sanctum_node_host <node_id>

sanctum_node_host manoir  # 192.168.1.10
sanctum_node_host chalet  # chalet.local

---

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.25

---

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-pro

---

sanctum_node_user

Return the SSH username for a node.

sanctum_node_user <node_id>

sanctum_node_user manoir  # bert

---

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"
fi

Note

This does a real network ping, so it takes a second or two. Don’t put it in a tight loop unless you enjoy watching your script crawl.

---

sanctum_node_ssh

SSH to a node over the LAN.

sanctum_node_ssh <node_id> [command...]

# Interactive shell
sanctum_node_ssh chalet

# Run a remote command
sanctum_node_ssh chalet 'uptime'

---

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

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

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"
fi

---

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  # 1977

---

sanctum_node_hub

Return the node ID of the hub node.

sanctum_node_hub

hub=$(sanctum_node_hub)
echo "$hub"  # manoir

---

Notification Functions

Source ~/.sanctum/lib/notify.sh for notification support. Because when your house has something to say, it should be able to say it.

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" high

Caution

Use high priority sparingly. It’s for things that actually need attention right now — disk full, service down, security event. Not for “backup completed successfully.” Nobody needs to be woken up because a backup worked. That’s what backups are supposed to do.

---

Complete Script Example

#!/bin/bash
source ~/.sanctum/lib/config.sh
source ~/.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" high
fi

Twenty lines. Queries the config, checks the network, sends a notification. This is what the shell library is for — turning what would be 200 lines of raw jq and ssh and osascript into something a human can read before coffee.