Execution context provides runtime information to extensions during execution via environment variables and template variable resolution.

Overview

When Homeboy executes extensions (via homeboy extension run or release pipeline steps), it builds an execution context containing:

• Extension metadata
• Project and component information (when available)
• Resolved settings
• Template variables
• Environment variables

Environment Variables

Homeboy sets the following environment variables before executing extensions:

Base Context Variables

• HOMEBOY_EXEC_CONTEXT_VERSION: Execution context protocol version (currently "1")

Extension Variables

• HOMEBOY_MODULE_ID: Extension identifier
• HOMEBOY_MODULE_PATH: Absolute path to extension directory

Project Context (when project is specified)

• HOMEBOY_PROJECT_ID: Project identifier
• HOMEBOY_DOMAIN: Project domain
• HOMEBOY_SITE_PATH: Project site path (absolute)

Component Context (when component is resolved)

• HOMEBOY_COMPONENT_ID: Component identifier
• HOMEBOY_COMPONENT_PATH: Absolute path to component directory

Settings

• HOMEBOY_SETTINGS_JSON: Merged effective settings as JSON string

Context Resolution Flow

Homeboy resolves execution context in the following order:

1. Extension Resolution

Extension is loaded from:

• Installed extensions directory (~/.config/homeboy/extensions/<extension_id>/)
• Or directly referenced via path (for development)

Extension metadata is extracted from <extension_id>.json manifest.

2. Project Resolution (optional)

If --project is specified:

• Project configuration is loaded (projects/<project_id>.json)
• Server configuration is loaded (via server_id)
• Database and API configuration is resolved

3. Component Resolution (optional)

If --component is specified:

• Component configuration is loaded (components/<component_id>.json)
• Component path is validated
• Component extension associations are identified

If --component is omitted:

• Homeboy attempts to resolve component from project’s component_ids
• First matching component is used
• Ambiguity is resolved via user prompt or explicit specification

4. Settings Merge

Extension settings are merged from multiple scopes in order (later scopes override earlier ones):

1. Project settings: projects/<project_id>.json -> extensions.<extension_id>.settings
2. Component settings: components/<component_id>.json -> extensions.<extension_id>.settings

Merged settings are available as:

• Environment variable: HOMEBOY_SETTINGS_JSON
• Template variable: {{settings.<key>}}

5. Template Variable Resolution

Template variables are resolved from:

• Execution context variables
• Extension manifest runtime.env definitions
• Extension platform configuration
• CLI input parameters

Template Variables Available in Execution

Standard Variables

Available in most contexts:

• {{projectId}}: Project ID
• {{domain}}: Project domain
• {{sitePath}}: Site root path
• {{cliPath}}: CLI executable path

Extension Runtime Variables

Available in runtime.run_command:

• {{extensionPath}}: Extension installation path
• {{entrypoint}}: Extension entrypoint file
• {{args}}: Command-line arguments

Project Context Variables

Available when project is resolved:

• {{db_host}}: Database host
• {{db_port}}: Database port
• {{db_name}}: Database name
• {{db_user}}: Database user
• {{db_password}}: Database password (from keychain)

Special Variables

Available in specific contexts:

• {{selected}}: Selected result rows (from --data flag)
• {{settings.<key>}}: Extension settings value
• {{payload.<key>}}: Action payload data
• {{release.<key>}}: Release configuration data

CLI Command Resolution

When extension provides top-level CLI commands, execution context is resolved similarly to homeboy extension run.

Extension Command Execution

homeboy wp <project_id> plugin list

Context resolution:

1. Extension is loaded (wordpress)
2. Project is resolved (<project_id>)
3. Component is resolved (if component specified or project has single component)
4. Settings are merged
5. Environment variables are set
6. Command is executed with template resolution

Extension Execution vs Release Pipeline Execution

Both homeboy extension run and extension.run pipeline steps share the same execution context behavior:

• Same template variable resolution
• Same settings merge logic
• Same environment variable setting
• Same CLI output contract

This ensures consistent behavior regardless of how extensions are invoked.

Example Contexts

Simple Extension Execution

homeboy extension run rust --component mycomponent

Environment variables:

HOMEBOY_EXEC_CONTEXT_VERSION=1
HOMEBOY_MODULE_ID=rust
HOMEBOY_MODULE_PATH=/home/user/.config/homeboy/extensions/rust
HOMEBOY_COMPONENT_ID=mycomponent
HOMEBOY_COMPONENT_PATH=/home/user/dev/mycomponent
HOMEBOY_SETTINGS_JSON={}

Full Context with Project

homeboy extension run wordpress --project mysite --component mytheme

Environment variables:

HOMEBOY_EXEC_CONTEXT_VERSION=1
HOMEBOY_MODULE_ID=wordpress
HOMEBOY_MODULE_PATH=/home/user/.config/homeboy/extensions/wordpress
HOMEBOY_PROJECT_ID=mysite
HOMEBOY_DOMAIN=mysite.com
HOMEBOY_SITE_PATH=/var/www/mysite
HOMEBOY_COMPONENT_ID=mytheme
HOMEBOY_COMPONENT_PATH=/home/user/dev/mytheme
HOMEBOY_SETTINGS_JSON={"php_version":"8.1"}

Template variables in run_command:

• {{extensionPath}} → /home/user/.config/homeboy/extensions/wordpress
• {{entrypoint}} → main.py (from manifest)
• {{args}} → CLI arguments passed to extension
• {{projectId}} → mysite
• {{domain}} → mysite.com
• {{settings.php_version}} → 8.1

Extension Environment Variables

Extensions can define additional environment variables in their manifest:

{
  "runtime": {
    "run_command": "python3 {{entrypoint}} {{args}}",
    "env": {
      "PYTHON_PATH": "{{extensionPath}}/lib",
      "CACHE_DIR": "{{extensionPath}}/cache"
    }
  }
}

These are set alongside Homeboy’s standard environment variables.

Context Limits and Validation

Validation Rules

• Required context: Some commands require project or component context
• Ambiguity resolution: Multiple components in project require explicit --component
• Path validation: Component paths must exist and be directories
• Extension validation: Extension must be installed or specified via path

Error Conditions

• Extension not found: Extension ID not in extensions directory
• Project not found: Project ID not in projects directory
• Component not found: Component ID not in components directory
• Context missing: Command requires project/component but none provided

Related

• Extension command – Extension execution
• Extension manifest schema – Runtime configuration
• Template variables – Template variable reference