Host Recipe Runner

A host daemon agent that manages recipe-runner worker processes for the Kemu platform.

Installation

See installation instructions at https://github.com/kemu-io/kemu-host-releases

After installation, the kemud binary will be available in your PATH (for global installs) or in node_modules/.bin/ (for local installs).

Configuration

Configuration is loaded from environment variables. Set these in your environment or use a .env file.

Required Configuration

| Variable | Description | Example | |----------|-------------|---------| | ENVIRONMENT_ID | ID generated when creating an environment from the Kemu Composer | env_xxxxxxx | | KEMU_API_KEY | Your Kemu API key (generate it in the Kemu Composer) | secret_xxx |

Optional Configuration

| Variable | Description | Default | |----------|-------------|---------| | HOST_ID_FILE_PATH | Path to file for persisting host ID between restarts | ~/.kemu/host-id | | MAX_WORKERS | Maximum number of concurrent worker processes allowed for this host | 10 | | SYNC_INTERVAL_SECONDS | Interval in seconds between sync polls to backend | 10 | | HEARTBEAT_INTERVAL_SECONDS | Interval in seconds between heartbeat reports to backend | 30 | | ARTIFACTS_DIR | Directory for storing downloaded deployment artifacts (ZIP files) | ~/.kemu/artifacts | | WORKSPACE_DIR | Working directory for worker processes | ~/.kemu/workspace | | RECIPE_RUNNER_COMMAND | Command to execute for recipe-runner workers (install separately via npm install @kemu-io/recipe-runner) | kemu | | SECRETS_KEY | Optional key for decrypting deployment secrets (only required if during deployment you set a custom encryption key) | Same as KEMU_API_KEY | | HOST_NAME | Display name for this host in backend dashboard | System hostname | | HOST_TAGS | JSON object of custom tags for host categorization | {} |

Configuration Details

HOST_ID_FILE_PATH: The host ID is assigned during first registration and persisted to this file. On subsequent starts, the agent reads this file instead of re-registering, ensuring the host maintains a stable identity.

ARTIFACTS_DIR: Each deployment gets its own subdirectory ({ARTIFACTS_DIR}/{deploymentId}/) where ZIP artifacts are extracted. The agent expects a .kemu file in the extracted contents.

GIT_REPOS_DIR: Git repositories are cloned once and reused across deployments. The agent performs git fetch and git checkout operations to update to the desired ref.

WORKSPACE_DIR: General working directory for any worker-related file operations (currently reserved for future use).

SECRETS_KEY: If not specified, falls back to KEMU_API_KEY. Used to decrypt any secrets mapped to the recipe. Decrypted secrets are injected as environment variables into worker processes.

HOST_TAGS: Useful for categorizing hosts (e.g., {"region":"us-east-1","tier":"premium"}). Tags are visible in the backend and can be used for deployment targeting.

Usage

Running the Agent

kemud

Or if installed locally:

npx kemud

The agent will:

1. Load configuration from environment
2. Register with backend (or load existing host ID)
3. Start sync and heartbeat loops
4. Reconcile deployment state (start/stop workers as needed)

The agent runs continuously until stopped with SIGTERM or SIGINT, at which point it will gracefully shut down all worker processes.

License

Proprietary software copyright (c) Kemu Platform. All rights reserved.