<!-- source: https://deepwiki.com/qhkm/zeptoclaw/11-services-and-orchestration -->

# Services and Orchestration

- src/channels/manager.rs
- src/channels/types.rs
- src/cli/gateway.rs
- src/cron/mod.rs
- src/heartbeat/mod.rs
- src/heartbeat/service.rs
- src/plugins/watcher.rs

**Purpose**: This page documents the background services, orchestration layer, and supervision mechanisms that coordinate ZeptoClaw's runtime components. It covers the Gateway Service (multi-channel orchestrator), CronService (persistent scheduler), HeartbeatService (periodic task monitor), health monitoring infrastructure, daemon supervision, and plugin watching.

For agent processing and tool execution flow, see [Agent Loop](/qhkm/zeptoclaw/3.2-agent-loop). For channel registration and lifecycle management, see [Channel Architecture](/qhkm/zeptoclaw/7.1-channel-architecture). For configuration hot-reload mechanics, see [Hot Reload](/qhkm/zeptoclaw/5.6-hot-reload).

## Gateway Service Architecture

The `cmd_gateway` function in [src/cli/gateway.rs27-30](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/gateway.rs#L27-L30) serves as the primary orchestration point for multi-channel deployments. It initializes and coordinates all runtime components in a specific sequence.

### Gateway Startup Sequence

```

```

**Sources**: [src/cli/gateway.rs27-560](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/gateway.rs#L27-L560)

### Containerized vs In-Process Modes

The gateway operates in two distinct modes determined by the `containerized` flag or configuration [src/cli/gateway.rs162-164](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/gateway.rs#L162-L164)

```

```

**Containerized mode resolution** ([src/cli/gateway.rs162-183](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/gateway.rs#L162-L183)):

- --containerized [docker|apple|auto] flag overrides config src/cli/gateway.rs 63-83
- resolve_backend() auto-detects available runtime src/cli/gateway.rs 166-168
- Docker: validates docker binary availability and image existence src/cli/gateway.rs 174-176
- Apple: requires macOS with container CLI src/cli/gateway.rs 178-181

**In-process mode** ([src/cli/gateway.rs239-268](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/gateway.rs#L239-L268)):

- Validates runtime provider support using RUNTIME_SUPPORTED_PROVIDERS src/cli/gateway.rs 20-21
- Creates agent directly with create_agent() src/cli/gateway.rs 23
- Sets usage metrics reference for the agent loop src/cli/gateway.rs 265-267

**Sources**: [src/cli/gateway.rs63-268](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/gateway.rs#L63-L268)

### Startup Guard and Degraded Mode

The `StartupGuard` detects consecutive crashes and disables dangerous tools to prevent infinite crash loops.

```

```

Configuration ([src/cli/gateway.rs37-61](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/gateway.rs#L37-L61)):

- config.gateway.startup_guard.enabled src/cli/gateway.rs 37
- crash_threshold (default: 3) src/cli/gateway.rs 39
- window_secs (default: 300) src/cli/gateway.rs 40

**Sources**: [src/cli/gateway.rs37-61](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/gateway.rs#L37-L61)

## CronService

`CronService` provides persistent scheduling for background agent turns. Jobs are stored in a `CronStore` and survive process restarts [src/cron/mod.rs234-240](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cron/mod.rs#L234-L240)

### Cron Architecture

```

```

**Sources**: [src/cron/mod.rs1-240](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cron/mod.rs#L1-L240)

### Schedule Types

**Cron expression format** ([src/cron/mod.rs147-183](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cron/mod.rs#L147-L183)):
Supports standard 5-field format: `minute hour day_of_month month day_of_week`.

**Sources**: [src/cron/mod.rs19-23](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cron/mod.rs#L19-L23) [src/cron/mod.rs147-183](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cron/mod.rs#L147-L183)

### Error Handling and Backoff

If a job fails, the service applies an exponential backoff schedule [src/cron/mod.rs87-93](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cron/mod.rs#L87-L93)

```

```

**Sources**: [src/cron/mod.rs87-93](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cron/mod.rs#L87-L93) [src/cron/mod.rs112-118](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cron/mod.rs#L112-L118)

## HeartbeatService

Monitors `HEARTBEAT.md` in the agent's workspace and triggers agent turns when actionable content is present [src/heartbeat/service.rs67-78](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/heartbeat/service.rs#L67-L78)

### Actionable Content Detection

The `is_empty()` function determines whether `HEARTBEAT.md` requires agent attention by skipping comments and unchecked checkboxes [src/heartbeat/service.rs188-200](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/heartbeat/service.rs#L188-L200)

```

```

**Sources**: [src/heartbeat/service.rs188-200](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/heartbeat/service.rs#L188-L200)

### Health Tracking

`HeartbeatService` tracks `consecutive_failures` [src/heartbeat/service.rs75](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/heartbeat/service.rs#L75-L75) If failures exceed the `failure_alert_threshold` (default 3), the service is considered unhealthy [src/heartbeat/service.rs182-185](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/heartbeat/service.rs#L182-L185)

**Sources**: [src/heartbeat/service.rs74-78](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/heartbeat/service.rs#L74-L78) [src/heartbeat/service.rs182-185](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/heartbeat/service.rs#L182-L185)

## Health Monitoring

ZeptoClaw provides two health monitoring systems: a legacy metrics-based server and a newer named-check registry.

### UsageMetrics

Lock-free atomic counters for gateway telemetry [src/cli/gateway.rs108](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/gateway.rs#L108-L108)

**Sources**: [src/cli/gateway.rs108](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/gateway.rs#L108-L108) [src/health.rs356-370](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/health.rs#L356-L370)

### HealthRegistry

Named component health checks with status tracking [src/cli/gateway.rs127-128](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/gateway.rs#L127-L128)

```

```

**Sources**: [src/cli/gateway.rs127-128](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/gateway.rs#L127-L128) [src/channels/manager.rs19](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/channels/manager.rs#L19-L19)

## Plugin Watcher

`PluginWatcher` detects new or modified binary plugins via filesystem polling without external dependencies [src/plugins/watcher.rs36-39](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/plugins/watcher.rs#L36-L39)

### Watcher Logic

The `scan()` method checks the modification time (`mtime`) of `plugin.json` manifests [src/plugins/watcher.rs49-121](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/plugins/watcher.rs#L49-L121)

```

```

**Binary Health Check**: The `check_binary_health()` function verifies that a plugin binary exists and is executable [src/plugins/watcher.rs157-159](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/plugins/watcher.rs#L157-L159)

**Sources**: [src/plugins/watcher.rs36-121](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/plugins/watcher.rs#L36-L121) [src/plugins/watcher.rs157-174](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/plugins/watcher.rs#L157-L174)

## Child Pages

For more detailed information on specific components, see the following pages:

- Gateway Service — cmd_gateway orchestration and startup sequence.
- CronService — Persistent scheduling, OnMiss policies, and backoff.
- HeartbeatService — HEARTBEAT.md monitoring and health tracking.
- Health Monitoring — HealthRegistry , UsageMetrics , and HTTP endpoints.
- Daemon Supervision — cmd_daemon and crash loop prevention.
- Routines Engine — Automation via the Routines system.
- r8r Bridge — WebSocket bridge to the r8r workflow engine.
