---
description: Clawrium configuration directory structure, file formats, and security considerations.
keywords: [configuration, hosts.yml, secrets.yml, SSH keys, XDG, settings]
---

# 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 claw 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:

```yaml
- 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
  claws:
    zeroclaw:
      version: "0.1.0"
      user: zc
      status: installed
      installed_at: "2026-04-01T12:00:00Z"
```

### secrets.yml

Contains secrets organized by claw instance:

```yaml
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:claw_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:

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

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

To restore:

```bash
# 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
```
