Configuration

Clawrium stores all configuration in a local directory that respects the XDG Base Directory specification.

Configuration Directory

By default, Clawrium stores configuration at:

~/.config/clawrium/

If XDG_CONFIG_HOME is set to an absolute path, Clawrium uses:

$XDG_CONFIG_HOME/clawrium/

Directory Structure

~/.config/clawrium/
├── hosts.yml           # Registered hosts and their metadata
├── secrets.yml         # Encrypted secrets for agent instances
└── keys/               # SSH keypairs for host authentication
    ├── host1.key       # Private key (permissions: 0600)
    └── host1.key.pub   # Public key

hosts.yml

Contains registered hosts and their configuration:

- hostname: 192.168.1.100
  alias: pi-lab
  key_id: 192.168.1.100
  port: 22
  user: xclm
  auth_method: key
  hardware:
    architecture: aarch64
    processor_cores: 4
    memtotal_mb: 4096
    gpu:
      present: false
  metadata:
    added_at: "2026-04-01T10:30:00Z"
    last_seen: "2026-04-05T08:15:00Z"
    tags:
      - production
      - arm
  agents:
    zeroclaw:
      version: "0.1.0"
      user: zc
      status: installed
      installed_at: "2026-04-01T12:00:00Z"

secrets.yml

Contains secrets organized by agent instance:

192.168.1.100:zeroclaw:zc-work:
  ANTHROPIC_API_KEY:
    description: "Claude API key for work"
    updated_at: "2026-04-01T10:30:00Z"
    value: <encrypted>
  GITHUB_TOKEN:
    description: "GitHub personal access token"
    updated_at: "2026-04-02T14:20:00Z"
    value: <encrypted>

The instance key format is hostname:agent_type:instance_name.

keys/

Per-host SSH keypairs generated on first clawctl host create. Each host has:

• <key_id>.key - Private key (Ed25519)
• <key_id>.key.pub - Public key

Key files have restrictive permissions (0600 for private, 0644 for public).

Security

File Permissions

The configuration directory and sensitive files are created with restrictive permissions:

Path	Permissions
~/.config/clawrium/	0700
secrets.yml	0600
*.key (private keys)	0600

Secret Storage

Secrets are stored locally and are never transmitted to remote hosts in plain text. The secrets.yml file should be protected and not committed to version control.

SSH Keys

Clawrium generates Ed25519 SSH keys for each host. These keys:

• Are stored in the local configuration directory
• Are used exclusively by the xclm management user
• Should be backed up securely and never shared

Environment Variables

Variable	Description
XDG_CONFIG_HOME	Override default configuration directory location

Backup and Recovery

To backup your Clawrium configuration:

# Backup entire configuration
cp -r ~/.config/clawrium ~/clawrium-backup

# Backup only hosts (excludes secrets)
cp ~/.config/clawrium/hosts.yml ~/hosts-backup.yml

To restore:

# Restore full configuration
cp -r ~/clawrium-backup ~/.config/clawrium

# Set correct permissions
chmod 700 ~/.config/clawrium
chmod 600 ~/.config/clawrium/secrets.yml
chmod 600 ~/.config/clawrium/keys/*.key