npm package: @kemu-io/kemu-host
Description: A host daemon agent that manages recipe-runner worker processes for the Kemu platform.
Latest version: 0.1.8

# 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

```bash
kemud
```

Or if installed locally:

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