Important: Homeboy uses centralized configuration only. There is no repo-local config file (no .homeboy.toml or .homeboy directory). All configuration lives in ~/.config/homeboy/.

Important: Homeboy uses centralized configuration only. There is no repo-local config file (no .homeboy.toml or .homeboy directory). All configuration lives in ~/.config/homeboy/.

Location

Important: Homeboy uses centralized configuration only. There is no repo-local config file (no .homeboy.toml or .homeboy directory). All configuration lives in ~/.config/homeboy/.

macOS

~/.config/homeboy/

Linux

~/.config/homeboy/

Windows

%APPDATA%homeboy

Homeboy stores all configuration in a universal directory location across operating systems.

Directory Structure

~/.config/homeboy/
├── homeboy/
│   └── homeboy.json           # Global app configuration
├── projects/
│   ├── <project_id>.json       # Project configurations
│   └── ...
├── servers/
│   ├── <server_id>.json       # Server configurations
│   └── ...
├── components/
│   ├── <component_id>.json    # Component configurations
│   └── ...
├── fleets/
│   ├── <fleet_id>.json        # Fleet configurations
│   └── ...
├── extensions/
│   ├── <extension_id>/
│   │   ├── <extension_id>.json   # Extension manifest
│   │   ├── docs/             # Extension documentation
│   │   └── ...              # Extension files
│   └── ...
├── keys/                     # SSH private keys (optional)
│   ├── <key_name>
│   └── ...
└── backups/                  # Configuration backups (optional)
    └── ...

File Details

Global App Configuration

Homeboy configuration lives under:

Typically: C:Users<username>AppDataRoaminghomeboy

{
  "storage": "builtin-filesystem",
  "installedModules": []
}

Project Configurations

File: ~/.config/homeboy/homeboy.json

Contains global Homeboy settings. Created automatically on first run with defaults.

Directory: ~/.config/homeboy/projects/

{
  "id": "extrachill",
  "name": "Extra Chill",
  "domain": "extrachill.com",
  "server_id": "production",
  "component_ids": ["theme", "api"]
}

Server Configurations

Each project is a separate JSON file named after the project ID.

Example: ~/.config/homeboy/projects/extrachill.json

Directory: ~/.config/homeboy/servers/

{
  "id": "production",
  "name": "Production Server",
  "host": "example.com",
  "user": "deploy"
}

Component Configurations

Each server is a separate JSON file named after the server ID.

Example: ~/.config/homeboy/servers/production.json

Directory: ~/.config/homeboy/components/

{
  "id": "theme",
  "local_path": "/home/dev/theme",
  "remote_path": "wp-content/themes/theme"
}

Fleet Configurations

Each component is a separate JSON file named after the component ID.

Example: ~/.config/homeboy/components/theme.json

Directory: ~/.config/homeboy/fleets/

{
  "id": "production",
  "project_ids": ["site-a", "site-b", "site-c"],
  "description": "Production sites sharing common plugins"
}

Extension Directory

Each fleet is a separate JSON file named after the fleet ID. Fleets group projects for coordinated operations.

Example: ~/.config/homeboy/fleets/production.json

• Extension manifest: <extension_id>/<extension_id>.json
• Extension documentation: <extension_id>/docs/
• Extension files: <extension_id>/ (executables, scripts, etc.)

Directory: ~/.config/homeboy/extensions/

Each extension is a subdirectory containing:

• Git clone (remote extensions)
• Symlink (local development extensions)

Keys Directory

Example: ~/.config/homeboy/extensions/wordpress/wordpress.json

Extensions are installed via:

Directory: ~/.config/homeboy/keys/

Backups Directory

Stores SSH private keys managed by Homeboy (optional). Keys can be referenced via relative paths in server configurations.

Example: keys/production_key

File Operations

Directory: ~/.config/homeboy/backups/

• No repo-local config files: Configuration is centralized
• No .homeboy directories: Avoids repo contamination
• Cross-repo compatibility: Multiple repos can reference the same configurations

Auto-creation

Configuration backups created by Homeboy (optional). Created before destructive operations.

• homeboy/ — First run
• projects/ — First project created
• servers/ — First server created
• components/ — First component created
• extensions/<extension_id>/ — Extension installed
• keys/ — Key referenced in server config
• backups/ — Backup created

Manual Configuration Editing

Homeboy does not write to directories outside the config directory:

Editing Tips

1. Use JSON validators: Ensure valid JSON syntax
2. Backup first: Copy file before editing
3. Reload changes: Some changes require command restart
4. Reference schemas: See schema documentation for field definitions

Schema References

• Component schema
• Project schema
• Server schema
• Fleet schema
• Extension manifest schema

Migration and Backups

Backup Strategy

Directories are created automatically when needed:

• Deleting configurations
• Major schema updates (optional)
• Bulk import operations

While Homeboy provides CLI commands for most operations, configurations can be edited manually:

Export Configurations

Homeboy creates backups before:

tar czf homeboy-config-backup.tar.gz ~/.config/homeboy/

Import Configurations

Backups are stored in ~/.config/homeboy/backups/ with timestamps.

tar xzf homeboy-config-backup.tar.gz -C ~/.config/

Security Permissions

Directory Permissions

Export all configurations to archive:

chmod 700 ~/.config/homeboy
chmod 700 ~/.config/homeboy/keys

File Permissions

Restore from backup:

chmod 600 ~/.config/homeboy/projects/*.json
chmod 600 ~/.config/homeboy/servers/*.json
chmod 600 ~/.config/homeboy/components/*.json

SSH Keys

Config directories should be restricted to user only:

chmod 600 ~/.config/homeboy/keys/*

Troubleshooting

Permission Denied Errors

Configuration files should be readable only by user:

# Fix permissions
chmod 700 ~/.config/homeboy
chmod 600 ~/.config/homeboy/projects/*.json
chmod 600 ~/.config/homeboy/servers/*.json
chmod 600 ~/.config/homeboy/components/*.json

Directory Not Found

SSH private keys must be restricted:

1. Verify config directory location for your platform
2. Create directory manually: mkdir -p ~/.config/homeboy
3. Run homeboy init to initialize

Corrupt Configuration

If Homeboy reports permission errors:

1. Restore from backup in ~/.config/homeboy/backups/
2. Or delete corrupt file and recreate via CLI commands

Related

• Init command – Initialize Homeboy
• Config command – Manage global configuration
• Project command – Manage project configurations
• Server command – Manage server configurations
• Component command – Manage component configurations
• Fleet command – Manage fleet configurations
• Extension command – Manage extension installations